diff --git a/apps/backend/internal/agent/runtime/agentctl/git.go b/apps/backend/internal/agent/runtime/agentctl/git.go index 33995c27cc..6246786405 100644 --- a/apps/backend/internal/agent/runtime/agentctl/git.go +++ b/apps/backend/internal/agent/runtime/agentctl/git.go @@ -30,6 +30,7 @@ type PRCreateResult struct { Provider string `json:"provider,omitempty"` Output string `json:"output,omitempty"` Error string `json:"error,omitempty"` + ErrorCode string `json:"error_code,omitempty"` } // GitPull performs a git pull operation on the worktree. diff --git a/apps/backend/internal/agent/runtime/agentctl/git_test.go b/apps/backend/internal/agent/runtime/agentctl/git_test.go index 33b1b84591..c2c954a833 100644 --- a/apps/backend/internal/agent/runtime/agentctl/git_test.go +++ b/apps/backend/internal/agent/runtime/agentctl/git_test.go @@ -341,7 +341,8 @@ func TestGitCreatePR_PostsFullPayloadAndDecodesResult(t *testing.T) { srv, got := captureServer(t, jsonResponder(http.StatusOK, `{ "success":true,"branch_pushed":true, "pr_url":"https://github.com/kdlbs/kandev/pull/1", - "provider":"github","output":"created" + "provider":"github","output":"created", + "error_code":"empty_remote_branch_publish_failed" }`)) result, err := newHTTPOnlyClient(srv.URL).GitCreatePR( @@ -383,6 +384,9 @@ func TestGitCreatePR_PostsFullPayloadAndDecodesResult(t *testing.T) { if result.Provider != "github" || result.Output != "created" { t.Errorf("provider/output = %q / %q, want github / created", result.Provider, result.Output) } + if result.ErrorCode != "empty_remote_branch_publish_failed" { + t.Errorf("error code = %q, want empty_remote_branch_publish_failed", result.ErrorCode) + } } func TestGitCreatePR_TreatsConflictAsNonError(t *testing.T) { diff --git a/apps/backend/internal/agent/runtime/lifecycle/env_preparer.go b/apps/backend/internal/agent/runtime/lifecycle/env_preparer.go index 4c2b93ad25..97d5b6b2ba 100644 --- a/apps/backend/internal/agent/runtime/lifecycle/env_preparer.go +++ b/apps/backend/internal/agent/runtime/lifecycle/env_preparer.go @@ -9,6 +9,7 @@ import ( "github.com/kandev/kandev/internal/agent/executor" "github.com/kandev/kandev/internal/agent/runtime/routingerr" "github.com/kandev/kandev/internal/common/logger" + "github.com/kandev/kandev/internal/repoclone" "github.com/kandev/kandev/internal/task/models" ) @@ -89,9 +90,11 @@ type RepoPrepareSpec struct { RemoteSyncHandled bool // RefreshRepository is an optional provider-authenticated refresh deferred // until worktree materialization. A valid reusable worktree bypasses it. - RefreshRepository func(context.Context) error - RepoSetupScript string - ContributionDestination *models.ContributionDestination + RefreshRepository func(context.Context) error + RefreshRepositoryWithState func(context.Context) (repoclone.RemoteRefState, error) + RemoteRefState repoclone.RemoteRefState + RepoSetupScript string + ContributionDestination *models.ContributionDestination // BranchSlug, when set, suffixes the worktree path as // {RepoName}-{BranchSlug} so two specs sharing a RepositoryID don't collide // on disk. @@ -138,7 +141,9 @@ type EnvPrepareRequest struct { RemoteSyncHandled bool // RefreshRepository is an optional provider-authenticated refresh deferred // until worktree materialization. A valid reusable worktree bypasses it. - RefreshRepository func(context.Context) error + RefreshRepository func(context.Context) error + RefreshRepositoryWithState func(context.Context) (repoclone.RemoteRefState, error) + RemoteRefState repoclone.RemoteRefState TaskDirName string // Per-task directory name within the workspace (e.g. "task-abc123") RepoName string // Repository slug used with TaskDirName to locate checkouts @@ -169,28 +174,30 @@ func (r *EnvPrepareRequest) RepoSpecs() []RepoPrepareSpec { return nil } return []RepoPrepareSpec{{ - TaskRepositoryID: r.TaskRepositoryID, - RepositoryID: r.RepositoryID, - RepositoryPath: r.RepositoryPath, - RepoName: r.RepoName, - BaseBranch: r.BaseBranch, - DefaultBranch: r.DefaultBranch, - CheckoutBranch: r.CheckoutBranch, - PRNumber: r.PRNumber, - RemoteContribution: r.RemoteContribution, - WorktreeID: r.WorktreeID, - WorkspaceReuseRequired: r.WorkspaceReuseRequired, - WorktreeBranch: r.WorktreeBranch, - WorktreeBranchPrefix: r.WorktreeBranchPrefix, - WorktreeBranchTemplate: r.WorktreeBranchTemplate, - WorktreeBranchTicket: r.WorktreeBranchTicket, - PullBeforeWorktree: r.PullBeforeWorktree, - RemoteSyncHandled: r.RemoteSyncHandled, - RefreshRepository: r.RefreshRepository, - RepoSetupScript: r.RepoSetupScript, - BranchSlug: r.BranchSlug, - BranchIdentitySlug: r.BranchIdentitySlug, - ContributionDestination: r.ContributionDestination, + TaskRepositoryID: r.TaskRepositoryID, + RepositoryID: r.RepositoryID, + RepositoryPath: r.RepositoryPath, + RepoName: r.RepoName, + BaseBranch: r.BaseBranch, + DefaultBranch: r.DefaultBranch, + CheckoutBranch: r.CheckoutBranch, + PRNumber: r.PRNumber, + RemoteContribution: r.RemoteContribution, + WorktreeID: r.WorktreeID, + WorkspaceReuseRequired: r.WorkspaceReuseRequired, + WorktreeBranch: r.WorktreeBranch, + WorktreeBranchPrefix: r.WorktreeBranchPrefix, + WorktreeBranchTemplate: r.WorktreeBranchTemplate, + WorktreeBranchTicket: r.WorktreeBranchTicket, + PullBeforeWorktree: r.PullBeforeWorktree, + RemoteSyncHandled: r.RemoteSyncHandled, + RefreshRepository: r.RefreshRepository, + RefreshRepositoryWithState: r.RefreshRepositoryWithState, + RemoteRefState: r.RemoteRefState, + RepoSetupScript: r.RepoSetupScript, + BranchSlug: r.BranchSlug, + BranchIdentitySlug: r.BranchIdentitySlug, + ContributionDestination: r.ContributionDestination, }} } diff --git a/apps/backend/internal/agent/runtime/lifecycle/env_preparer_worktree.go b/apps/backend/internal/agent/runtime/lifecycle/env_preparer_worktree.go index b64c160476..270e9d80de 100644 --- a/apps/backend/internal/agent/runtime/lifecycle/env_preparer_worktree.go +++ b/apps/backend/internal/agent/runtime/lifecycle/env_preparer_worktree.go @@ -285,31 +285,33 @@ func (p *WorktreePreparer) createWorktreeWithSync( // manager's CreateRequest. Progress callbacks are wired by the caller. func buildWorktreeCreateRequest(req *EnvPrepareRequest) worktree.CreateRequest { return worktree.CreateRequest{ - TaskID: req.TaskID, - WorkspaceID: req.WorkspaceID, - SessionID: req.SessionID, - TaskEnvironmentID: req.TaskEnvironmentID, - TaskTitle: req.TaskTitle, - RepositoryID: req.RepositoryID, - RepositoryPath: req.RepositoryPath, - BaseBranch: req.BaseBranch, - FallbackBaseBranch: req.DefaultBranch, - CheckoutBranch: req.CheckoutBranch, - PRNumber: req.PRNumber, - RemoteContribution: req.RemoteContribution, - WorktreeBranchPrefix: req.WorktreeBranchPrefix, - WorktreeBranchTemplate: req.WorktreeBranchTemplate, - WorktreeBranchTicket: req.WorktreeBranchTicket, - PullBeforeWorktree: req.PullBeforeWorktree, - RemoteSyncHandled: req.RemoteSyncHandled, - RefreshRepository: req.RefreshRepository, - WorktreeID: req.WorktreeID, - ReuseRequired: req.WorkspaceReuseRequired, - TaskDirName: req.TaskDirName, - RepoName: req.RepoName, - BranchSlug: req.BranchSlug, - BranchIdentitySlug: req.BranchIdentitySlug, - ContributionDestination: req.ContributionDestination, + TaskID: req.TaskID, + WorkspaceID: req.WorkspaceID, + SessionID: req.SessionID, + TaskEnvironmentID: req.TaskEnvironmentID, + TaskTitle: req.TaskTitle, + RepositoryID: req.RepositoryID, + RepositoryPath: req.RepositoryPath, + BaseBranch: req.BaseBranch, + FallbackBaseBranch: req.DefaultBranch, + CheckoutBranch: req.CheckoutBranch, + PRNumber: req.PRNumber, + RemoteContribution: req.RemoteContribution, + WorktreeBranchPrefix: req.WorktreeBranchPrefix, + WorktreeBranchTemplate: req.WorktreeBranchTemplate, + WorktreeBranchTicket: req.WorktreeBranchTicket, + PullBeforeWorktree: req.PullBeforeWorktree, + RemoteSyncHandled: req.RemoteSyncHandled, + RefreshRepository: req.RefreshRepository, + RefreshRepositoryWithState: req.RefreshRepositoryWithState, + RemoteRefState: req.RemoteRefState, + WorktreeID: req.WorktreeID, + ReuseRequired: req.WorkspaceReuseRequired, + TaskDirName: req.TaskDirName, + RepoName: req.RepoName, + BranchSlug: req.BranchSlug, + BranchIdentitySlug: req.BranchIdentitySlug, + ContributionDestination: req.ContributionDestination, // Export resolved executor-profile env vars into the repository setup // script so tokens (e.g. an npm auth token) are available during // install. Set for both single-repo and multi-repo launches, which both @@ -536,6 +538,8 @@ func (p *WorktreePreparer) prepareOneRepo( subReq.PullBeforeWorktree = spec.PullBeforeWorktree subReq.RemoteSyncHandled = spec.RemoteSyncHandled subReq.RefreshRepository = spec.RefreshRepository + subReq.RefreshRepositoryWithState = spec.RefreshRepositoryWithState + subReq.RemoteRefState = spec.RemoteRefState subReq.BranchSlug = spec.BranchSlug subReq.BranchIdentitySlug = repoBranchIdentitySlug(spec) // Strip the multi-repo list to avoid re-entering the multi-repo branch. diff --git a/apps/backend/internal/agent/runtime/lifecycle/manager_launch.go b/apps/backend/internal/agent/runtime/lifecycle/manager_launch.go index 21545888a1..f5fda53439 100644 --- a/apps/backend/internal/agent/runtime/lifecycle/manager_launch.go +++ b/apps/backend/internal/agent/runtime/lifecycle/manager_launch.go @@ -1016,39 +1016,41 @@ func (m *Manager) runEnvironmentPreparerWithProgress( func buildEnvPrepareRequest(req *LaunchRequest, workspacePath string, execName executor.Name) *EnvPrepareRequest { repoSetupScript, _ := req.Metadata[MetadataKeyRepoSetupScript].(string) prepReq := &EnvPrepareRequest{ - TaskID: req.TaskID, - WorkspaceID: req.WorkspaceID, - SessionID: req.SessionID, - TaskEnvironmentID: req.TaskEnvironmentID, - TaskTitle: req.TaskTitle, - ExecutorType: execName, - WorkspacePath: workspacePath, - RepositoryPath: req.RepositoryPath, - RepositoryID: req.RepositoryID, - TaskRepositoryID: req.TaskRepositoryID, - UseWorktree: req.UseWorktree, - WorkspaceReuseRequired: req.WorkspaceReuseRequired, - WorktreeID: req.WorktreeID, - SetupScript: req.SetupScript, - RepoSetupScript: repoSetupScript, - BaseBranch: req.BaseBranch, - DefaultBranch: req.DefaultBranch, - CheckoutBranch: req.CheckoutBranch, - PRNumber: req.PRNumber, - RemoteContribution: req.RemoteContribution, - ContributionDestination: req.ContributionDestination, - WorktreeBranch: getMetadataString(req.Metadata, MetadataKeyWorktreeBranch), - WorktreeBranchPrefix: req.WorktreeBranchPrefix, - WorktreeBranchTemplate: req.WorktreeBranchTemplate, - WorktreeBranchTicket: req.WorktreeBranchTicket, - PullBeforeWorktree: req.PullBeforeWorktree, - RemoteSyncHandled: req.RemoteSyncHandled, - RefreshRepository: req.RefreshRepository, - TaskDirName: req.TaskDirName, - RepoName: req.RepoName, - BranchSlug: req.BranchSlug, - BranchIdentitySlug: req.BranchIdentitySlug, - Env: req.Env, + TaskID: req.TaskID, + WorkspaceID: req.WorkspaceID, + SessionID: req.SessionID, + TaskEnvironmentID: req.TaskEnvironmentID, + TaskTitle: req.TaskTitle, + ExecutorType: execName, + WorkspacePath: workspacePath, + RepositoryPath: req.RepositoryPath, + RepositoryID: req.RepositoryID, + TaskRepositoryID: req.TaskRepositoryID, + UseWorktree: req.UseWorktree, + WorkspaceReuseRequired: req.WorkspaceReuseRequired, + WorktreeID: req.WorktreeID, + SetupScript: req.SetupScript, + RepoSetupScript: repoSetupScript, + BaseBranch: req.BaseBranch, + DefaultBranch: req.DefaultBranch, + CheckoutBranch: req.CheckoutBranch, + PRNumber: req.PRNumber, + RemoteContribution: req.RemoteContribution, + ContributionDestination: req.ContributionDestination, + WorktreeBranch: getMetadataString(req.Metadata, MetadataKeyWorktreeBranch), + WorktreeBranchPrefix: req.WorktreeBranchPrefix, + WorktreeBranchTemplate: req.WorktreeBranchTemplate, + WorktreeBranchTicket: req.WorktreeBranchTicket, + PullBeforeWorktree: req.PullBeforeWorktree, + RemoteSyncHandled: req.RemoteSyncHandled, + RefreshRepository: req.RefreshRepository, + RefreshRepositoryWithState: req.RefreshRepositoryWithState, + RemoteRefState: req.RemoteRefState, + TaskDirName: req.TaskDirName, + RepoName: req.RepoName, + BranchSlug: req.BranchSlug, + BranchIdentitySlug: req.BranchIdentitySlug, + Env: req.Env, } // Multi-repo: forward the repo list when the launch request carries one. // Each per-repo entry inherits the request-level RepoSetupScript when its @@ -1061,26 +1063,28 @@ func buildEnvPrepareRequest(req *LaunchRequest, workspacePath string, execName e setup = repoSetupScript } specs = append(specs, RepoPrepareSpec{ - TaskRepositoryID: r.TaskRepositoryID, - RepositoryID: r.RepositoryID, - RepositoryPath: r.RepositoryPath, - RepoName: r.RepoName, - BaseBranch: r.BaseBranch, - DefaultBranch: r.DefaultBranch, - CheckoutBranch: r.CheckoutBranch, - PRNumber: r.PRNumber, - RemoteContribution: r.RemoteContribution, - WorktreeID: r.WorktreeID, - WorktreeBranchPrefix: r.WorktreeBranchPrefix, - WorktreeBranchTemplate: r.WorktreeBranchTemplate, - WorktreeBranchTicket: r.WorktreeBranchTicket, - PullBeforeWorktree: r.PullBeforeWorktree, - RemoteSyncHandled: r.RemoteSyncHandled, - RefreshRepository: r.RefreshRepository, - RepoSetupScript: setup, - BranchSlug: r.BranchSlug, - BranchIdentitySlug: r.BranchIdentitySlug, - ContributionDestination: r.ContributionDestination, + TaskRepositoryID: r.TaskRepositoryID, + RepositoryID: r.RepositoryID, + RepositoryPath: r.RepositoryPath, + RepoName: r.RepoName, + BaseBranch: r.BaseBranch, + DefaultBranch: r.DefaultBranch, + CheckoutBranch: r.CheckoutBranch, + PRNumber: r.PRNumber, + RemoteContribution: r.RemoteContribution, + WorktreeID: r.WorktreeID, + WorktreeBranchPrefix: r.WorktreeBranchPrefix, + WorktreeBranchTemplate: r.WorktreeBranchTemplate, + WorktreeBranchTicket: r.WorktreeBranchTicket, + PullBeforeWorktree: r.PullBeforeWorktree, + RemoteSyncHandled: r.RemoteSyncHandled, + RefreshRepository: r.RefreshRepository, + RefreshRepositoryWithState: r.RefreshRepositoryWithState, + RemoteRefState: r.RemoteRefState, + RepoSetupScript: setup, + BranchSlug: r.BranchSlug, + BranchIdentitySlug: r.BranchIdentitySlug, + ContributionDestination: r.ContributionDestination, }) } prepReq.Repositories = specs diff --git a/apps/backend/internal/agent/runtime/lifecycle/types.go b/apps/backend/internal/agent/runtime/lifecycle/types.go index 4ef05e7a53..ea244a51de 100644 --- a/apps/backend/internal/agent/runtime/lifecycle/types.go +++ b/apps/backend/internal/agent/runtime/lifecycle/types.go @@ -18,6 +18,7 @@ import ( "github.com/kandev/kandev/internal/agentruntime" "github.com/kandev/kandev/internal/common/ports" mcpprofile "github.com/kandev/kandev/internal/mcp/profile" + "github.com/kandev/kandev/internal/repoclone" "github.com/kandev/kandev/internal/task/models" v1 "github.com/kandev/kandev/pkg/api/v1" "go.opentelemetry.io/otel/trace" @@ -768,12 +769,14 @@ type RepoLaunchSpec struct { RemoteSyncHandled bool // RefreshRepository is an optional provider-authenticated refresh deferred // until worktree materialization. A valid reusable worktree bypasses it. - RefreshRepository func(context.Context) error - RepoSetupScript string // Repository-level setup script (optional) - RepoCleanupScript string // Repository-level cleanup script (optional) - CopyFiles string // Comma-separated paths/globs to copy from the source repo (gitignored .env / config files) - ContributionDestination *models.ContributionDestination - ComparisonTarget *models.ComparisonTarget + RefreshRepository func(context.Context) error + RefreshRepositoryWithState func(context.Context) (repoclone.RemoteRefState, error) + RemoteRefState repoclone.RemoteRefState + RepoSetupScript string // Repository-level setup script (optional) + RepoCleanupScript string // Repository-level cleanup script (optional) + CopyFiles string // Comma-separated paths/globs to copy from the source repo (gitignored .env / config files) + ContributionDestination *models.ContributionDestination + ComparisonTarget *models.ComparisonTarget // BranchSlug, when set, suffixes the worktree directory as // {RepoName}-{BranchSlug} so multi-branch tasks (same repo, multiple // branches) don't collide. @@ -911,8 +914,10 @@ type LaunchRequest struct { RemoteSyncHandled bool // Authenticated provider refresh already completed // RefreshRepository is an optional provider-authenticated refresh deferred // until worktree materialization. A valid reusable worktree bypasses it. - RefreshRepository func(context.Context) error - ContributionDestination *models.ContributionDestination + RefreshRepository func(context.Context) error + RefreshRepositoryWithState func(context.Context) (repoclone.RemoteRefState, error) + RemoteRefState repoclone.RemoteRefState + ContributionDestination *models.ContributionDestination // Task directory mode: place worktree at ~/.kandev/tasks/{TaskDirName}/{RepoName}/ TaskDirName string // Semantic task directory name (e.g. "fix-bug_ab12") @@ -946,27 +951,29 @@ func (r *LaunchRequest) RepoSpecs() []RepoLaunchSpec { return nil } return []RepoLaunchSpec{{ - TaskRepositoryID: r.TaskRepositoryID, - RepositoryID: r.RepositoryID, - RepositoryPath: r.RepositoryPath, - RepoName: r.RepoName, - BaseBranch: r.BaseBranch, - DefaultBranch: r.DefaultBranch, - CheckoutBranch: r.CheckoutBranch, - PRNumber: r.PRNumber, - RemoteContribution: r.RemoteContribution, - ComparisonTarget: r.ComparisonTarget, - ContributionDestination: r.ContributionDestination, - WorktreeID: r.WorktreeID, - WorktreeBranchPrefix: r.WorktreeBranchPrefix, - WorktreeBranchTemplate: r.WorktreeBranchTemplate, - WorktreeBranchTicket: r.WorktreeBranchTicket, - PullBeforeWorktree: r.PullBeforeWorktree, - RemoteSyncHandled: r.RemoteSyncHandled, - RefreshRepository: r.RefreshRepository, - CopyFiles: r.CopyFiles, - BranchSlug: r.BranchSlug, - BranchIdentitySlug: r.BranchIdentitySlug, + TaskRepositoryID: r.TaskRepositoryID, + RepositoryID: r.RepositoryID, + RepositoryPath: r.RepositoryPath, + RepoName: r.RepoName, + BaseBranch: r.BaseBranch, + DefaultBranch: r.DefaultBranch, + CheckoutBranch: r.CheckoutBranch, + PRNumber: r.PRNumber, + RemoteContribution: r.RemoteContribution, + ComparisonTarget: r.ComparisonTarget, + ContributionDestination: r.ContributionDestination, + WorktreeID: r.WorktreeID, + WorktreeBranchPrefix: r.WorktreeBranchPrefix, + WorktreeBranchTemplate: r.WorktreeBranchTemplate, + WorktreeBranchTicket: r.WorktreeBranchTicket, + PullBeforeWorktree: r.PullBeforeWorktree, + RemoteSyncHandled: r.RemoteSyncHandled, + RefreshRepository: r.RefreshRepository, + RefreshRepositoryWithState: r.RefreshRepositoryWithState, + RemoteRefState: r.RemoteRefState, + CopyFiles: r.CopyFiles, + BranchSlug: r.BranchSlug, + BranchIdentitySlug: r.BranchIdentitySlug, }} } diff --git a/apps/backend/internal/agentctl/server/process/git.go b/apps/backend/internal/agentctl/server/process/git.go index 25ab352d42..a1d898ea0d 100644 --- a/apps/backend/internal/agentctl/server/process/git.go +++ b/apps/backend/internal/agentctl/server/process/git.go @@ -249,6 +249,15 @@ func (g *GitOperator) runGitCommand(ctx context.Context, args ...string) (string continue } + // Empty-remote publication uses an immutable commit-to-branch refspec. + // Validate it before the generic slash-bearing reference check. + if source, destination, ok := strings.Cut(arg, ":refs/heads/"); ok { + if securityutil.LooksLikeCommitSHA(source) && + securityutil.IsValidBranchName(destination) { + continue + } + } + // Validate branch references (e.g., "origin/branch", "upstream/main") // This provides defense-in-depth even though branches are validated at call sites if strings.Contains(arg, "/") { @@ -494,6 +503,16 @@ func (g *GitOperator) Push(ctx context.Context, force bool, setUpstream bool) (* result.Error = err.Error() return result, nil } + basePublication := emptyRemotePublication{} + if g.remoteContribution == nil && g.contributionDestination == nil { + basePublication = g.prepareEmptyRemotePublication(ctx, "") + if basePublication.err != nil { + result.Error = basePublication.err.Error() + result.ErrorCode = basePublication.errorCode + result.Output = basePublication.output + return result, nil + } + } args := []string{"push"} shouldSetUpstream := setUpstream || g.getUpstreamRef(ctx) == "" @@ -524,8 +543,13 @@ func (g *GitOperator) Push(ctx context.Context, force bool, setUpstream bool) (* if err != nil { result.Error = err.Error() + if basePublication.active { + result.ErrorCode = emptyRemoteBranchPublishFailedErrorCode + result.Output = combineGitOutputs(basePublication.output, output) + } return result, nil } + result.Output = combineGitOutputs(basePublication.output, output) result.Success = true g.logger.Info("push completed", @@ -1207,6 +1231,7 @@ type PRCreateResult struct { Provider string `json:"provider,omitempty"` Output string `json:"output,omitempty"` Error string `json:"error,omitempty"` + ErrorCode string `json:"error_code,omitempty"` } // CreatePR creates a pull request using the repository host's CLI. @@ -1294,13 +1319,26 @@ func (g *GitOperator) CreatePR(ctx context.Context, title, body, baseBranch stri return result, nil } + basePublication := g.prepareEmptyRemotePublication(ctx, baseBranch) + if basePublication.err != nil { + result.Error = basePublication.err.Error() + result.ErrorCode = basePublication.errorCode + result.Output = basePublication.output + return result, nil + } + pushOutput, err := g.runGitCommand(ctx, "push", "--set-upstream", "origin", "HEAD") if err != nil { sanitizedOutput := g.sanitizePRFailure(pushOutput, title, body) result.Error = fmt.Sprintf("failed to push branch: %s", sanitizedOutput) - result.Output = sanitizedOutput + result.Output = combineGitOutputs(basePublication.output, sanitizedOutput) + if basePublication.active { + result.ErrorCode = emptyRemoteBranchPublishFailedErrorCode + } return result, nil } + result.Output = combineGitOutputs(basePublication.output, g.sanitizeGitPushOutput(pushOutput)) + result.BranchPushed = true g.logger.Debug("pushed branch to remote", zap.String("output", g.sanitizeGitPushOutput(pushOutput))) switch provider { diff --git a/apps/backend/internal/agentctl/server/process/git_empty_remote.go b/apps/backend/internal/agentctl/server/process/git_empty_remote.go new file mode 100644 index 0000000000..ce50c38225 --- /dev/null +++ b/apps/backend/internal/agentctl/server/process/git_empty_remote.go @@ -0,0 +1,230 @@ +package process + +import ( + "context" + "errors" + "fmt" + "strings" + + "github.com/kandev/kandev/internal/common/securityutil" + "github.com/kandev/kandev/internal/gitbootstrap" + "go.uber.org/zap" +) + +const ( + emptyRemoteRemoteChangedErrorCode = "empty_remote_remote_changed" + emptyRemoteBasePublishFailedErrorCode = "empty_remote_base_publish_failed" + emptyRemoteBranchPublishFailedErrorCode = "empty_remote_branch_publish_failed" +) + +type emptyRemotePublication struct { + active bool + output string + errorCode string + err error +} + +func (g *GitOperator) prepareEmptyRemotePublication(ctx context.Context, requestedBaseBranch string) emptyRemotePublication { + baseBranch, baseline, result := g.validateEmptyRemoteBaseline(ctx, requestedBaseBranch) + if result.err != nil || baseBranch == "" { + return result + } + + refs, err := g.advertisedOriginRefs(ctx) + if err != nil { + return emptyRemotePublication{ + active: true, + errorCode: emptyRemoteBasePublishFailedErrorCode, + err: fmt.Errorf("could not verify the remote before publishing the base branch: %w", err), + } + } + baseRef := "refs/heads/" + baseBranch + if len(refs) == 0 { + return g.publishEmptyRemoteBase(ctx, baseBranch, baseline) + } + if refs[baseRef] == baseline.Commit { + if retireErr := gitbootstrap.Retire(ctx, g.workDir, baseline); retireErr != nil { + return emptyRemotePublication{ + active: true, + errorCode: emptyRemoteBasePublishFailedErrorCode, + err: fmt.Errorf("empty-remote base is already published but its local marker could not be retired: %s", g.sanitizePRFailure(retireErr.Error())), + } + } + return emptyRemotePublication{active: true} + } + return emptyRemotePublication{ + active: true, + errorCode: emptyRemoteRemoteChangedErrorCode, + err: errors.New("the remote gained Git history before the empty-remote base was published; refresh the task and retry"), + } +} + +func (g *GitOperator) validateEmptyRemoteBaseline( + ctx context.Context, requestedBaseBranch string, +) (string, gitbootstrap.Baseline, emptyRemotePublication) { + requestedBaseBranch = normalizeEmptyRemoteBaseBranch(requestedBaseBranch) + baseBranch := g.emptyRemoteBaseBranch("") + if baseBranch == "" { + baseBranch = requestedBaseBranch + } + if baseBranch == "" || !securityutil.IsValidBaseBranchRef(baseBranch) { + return "", gitbootstrap.Baseline{}, emptyRemotePublication{} + } + baseline, present, err := gitbootstrap.Validate(ctx, g.workDir, baseBranch) + if errors.Is(err, gitbootstrap.ErrBaselineConflict) { + return "", gitbootstrap.Baseline{}, emptyRemotePublication{ + active: true, + errorCode: emptyRemoteRemoteChangedErrorCode, + err: errors.New("the local empty-remote baseline no longer matches Git history; refresh the task and retry"), + } + } + if err != nil { + return "", gitbootstrap.Baseline{}, emptyRemotePublication{ + active: true, + errorCode: emptyRemoteBasePublishFailedErrorCode, + err: err, + } + } + if !present { + return "", gitbootstrap.Baseline{}, emptyRemotePublication{} + } + if requestedBaseBranch != "" && requestedBaseBranch != baseBranch { + return "", gitbootstrap.Baseline{}, emptyRemotePublication{ + active: true, + errorCode: emptyRemoteRemoteChangedErrorCode, + err: errors.New("the requested change-request base does not match the empty-remote task base; refresh the task and retry"), + } + } + return baseBranch, baseline, emptyRemotePublication{active: true} +} + +func (g *GitOperator) publishEmptyRemoteBase( + ctx context.Context, baseBranch string, baseline gitbootstrap.Baseline, +) emptyRemotePublication { + baseRef := "refs/heads/" + baseBranch + lease := "--force-with-lease=" + baseRef + ":" + refspec := baseline.Commit + ":" + baseRef + output, pushErr := g.runGitCommand(ctx, "push", lease, "origin", refspec) + if pushErr != nil { + if currentRefs, probeErr := g.advertisedOriginRefs(ctx); probeErr == nil && len(currentRefs) > 0 { + return emptyRemotePublication{ + active: true, + output: g.sanitizeGitPushOutput(output), + errorCode: emptyRemoteRemoteChangedErrorCode, + err: errors.New("the remote changed while the empty-remote base was being published; refresh the task and retry"), + } + } + return emptyRemotePublication{ + active: true, + output: g.sanitizeGitPushOutput(output), + errorCode: emptyRemoteBasePublishFailedErrorCode, + err: fmt.Errorf("failed to publish the empty-remote base branch: %s", g.sanitizePRFailure(output, "", "")), + } + } + + result := g.validatePublishedEmptyRemoteBase(ctx, baseBranch, baseline) + if result.err != nil { + result.output = g.sanitizeGitPushOutput(output) + return result + } + if retireErr := gitbootstrap.Retire(ctx, g.workDir, baseline); retireErr != nil { + return emptyRemotePublication{ + active: true, + output: g.sanitizeGitPushOutput(output), + errorCode: emptyRemoteBasePublishFailedErrorCode, + err: fmt.Errorf("empty-remote base was published but its local marker could not be retired: %s", g.sanitizePRFailure(retireErr.Error())), + } + } + return emptyRemotePublication{active: true, output: g.sanitizeGitPushOutput(output)} +} + +func (g *GitOperator) validatePublishedEmptyRemoteBase( + ctx context.Context, baseBranch string, baseline gitbootstrap.Baseline, +) emptyRemotePublication { + localBaseline, localPresent, localErr := gitbootstrap.Validate(ctx, g.workDir, baseBranch) + if localErr != nil { + if errors.Is(localErr, gitbootstrap.ErrBaselineConflict) { + return emptyRemotePublication{ + active: true, + errorCode: emptyRemoteRemoteChangedErrorCode, + err: errors.New("the local empty-remote baseline changed while the base was being published; refresh the task and retry"), + } + } + return emptyRemotePublication{ + active: true, + errorCode: emptyRemoteBasePublishFailedErrorCode, + err: fmt.Errorf("could not revalidate the empty-remote baseline: %s", g.sanitizePRFailure(localErr.Error())), + } + } + if !localPresent || localBaseline.Commit != baseline.Commit { + return emptyRemotePublication{ + active: true, + errorCode: emptyRemoteRemoteChangedErrorCode, + err: errors.New("the local empty-remote baseline changed while the base was being published; refresh the task and retry"), + } + } + + publishedRefs, probeErr := g.advertisedOriginRefs(ctx) + if probeErr != nil { + return emptyRemotePublication{ + active: true, + errorCode: emptyRemoteBasePublishFailedErrorCode, + err: fmt.Errorf("the empty-remote base was published but could not be verified: %s", g.sanitizePRFailure(probeErr.Error())), + } + } + baseRef := "refs/heads/" + baseBranch + if len(publishedRefs) != 1 || publishedRefs[baseRef] != baseline.Commit { + return emptyRemotePublication{ + active: true, + errorCode: emptyRemoteRemoteChangedErrorCode, + err: errors.New("the remote changed while the empty-remote base was being published; refresh the task and retry"), + } + } + return emptyRemotePublication{} +} + +func (g *GitOperator) emptyRemoteBaseBranch(requestedBaseBranch string) string { + branch := strings.TrimSpace(requestedBaseBranch) + if branch == "" && g.workspaceTracker != nil { + branch = strings.TrimSpace(g.workspaceTracker.BaseBranch()) + } + return normalizeEmptyRemoteBaseBranch(branch) +} + +func normalizeEmptyRemoteBaseBranch(branch string) string { + branch = strings.TrimSpace(branch) + branch = strings.TrimPrefix(branch, "origin/") + return strings.TrimPrefix(branch, "refs/heads/") +} + +func (g *GitOperator) advertisedOriginRefs(ctx context.Context) (map[string]string, error) { + output, err := g.runGitCommand(ctx, "ls-remote", "--refs", "origin") + if err != nil { + g.logger.Debug("could not inspect remote refs before empty-remote publication", + zap.String("error", g.sanitizePRFailure(err.Error()))) + return nil, errors.New("remote ref advertisement unavailable") + } + refs := make(map[string]string) + for _, line := range strings.Split(strings.TrimSpace(output), "\n") { + fields := strings.Fields(strings.TrimSpace(line)) + if len(fields) != 2 || !strings.HasPrefix(fields[1], "refs/") { + if len(fields) == 0 { + continue + } + return nil, errors.New("malformed remote ref advertisement") + } + refs[fields[1]] = fields[0] + } + return refs, nil +} + +func combineGitOutputs(first, second string) string { + first, second = strings.TrimSpace(first), strings.TrimSpace(second) + if first == "" { + return second + } + if second == "" { + return first + } + return first + "\n" + second +} diff --git a/apps/backend/internal/agentctl/server/process/git_empty_remote_test.go b/apps/backend/internal/agentctl/server/process/git_empty_remote_test.go new file mode 100644 index 0000000000..43ea68ea6d --- /dev/null +++ b/apps/backend/internal/agentctl/server/process/git_empty_remote_test.go @@ -0,0 +1,365 @@ +package process + +import ( + "context" + "fmt" + "os" + "os/exec" + "path/filepath" + "runtime" + "strings" + "testing" + + "github.com/kandev/kandev/internal/gitbootstrap" +) + +func TestGitOperatorPushPublishesEmptyRemoteBaseBeforeTaskBranch(t *testing.T) { + repoDir, originDir, operator := setupEmptyRemoteTaskRepo(t) + + result, err := operator.Push(context.Background(), false, false) + if err != nil { + t.Fatalf("Push() error = %v", err) + } + if !result.Success { + t.Fatalf("Push() result = %+v", result) + } + baseSHA := strings.TrimSpace(runGit(t, repoDir, "rev-parse", "refs/heads/main")) + if got := strings.TrimSpace(runGit(t, originDir, "rev-parse", "refs/heads/main")); got != baseSHA { + t.Fatalf("remote base = %q, want local baseline %q", got, baseSHA) + } + branchSHA := strings.TrimSpace(runGit(t, repoDir, "rev-parse", "HEAD")) + if got := strings.TrimSpace(runGit(t, originDir, "rev-parse", "refs/heads/feature/empty")); got != branchSHA { + t.Fatalf("remote task branch = %q, want %q", got, branchSHA) + } + markerRef, err := gitbootstrap.MarkerRef("main") + if err != nil { + t.Fatal(err) + } + if hasLocalRef(t, repoDir, markerRef) { + t.Fatalf("bootstrap marker %q remains after successful publication", markerRef) + } +} + +func TestGitOperatorPushPublishesAnotherTaskBranchAfterBaseInitialization(t *testing.T) { + repoDir, originDir, operator := setupEmptyRemoteTaskRepo(t) + + first, err := operator.Push(context.Background(), false, false) + if err != nil { + t.Fatalf("first Push() error = %v", err) + } + if !first.Success { + t.Fatalf("first Push() result = %+v", first) + } + + runGit(t, repoDir, "checkout", "-b", "feature/second", "main") + if err := os.WriteFile(filepath.Join(repoDir, "second.txt"), []byte("second\n"), 0o644); err != nil { + t.Fatal(err) + } + runGit(t, repoDir, "add", "second.txt") + runGit(t, repoDir, "commit", "-m", "second task change") + + second, err := operator.Push(context.Background(), false, false) + if err != nil { + t.Fatalf("second Push() error = %v", err) + } + if !second.Success { + t.Fatalf("second Push() result = %+v", second) + } + if got := strings.TrimSpace(runGit(t, originDir, "rev-parse", "refs/heads/feature/second")); got == "" { + t.Fatal("second task branch was not published after base initialization") + } +} + +func TestGitOperatorPushAcceptsMarkedBaseWithUnrelatedRemoteRefs(t *testing.T) { + repoDir, originDir, operator := setupEmptyRemoteTaskRepo(t) + runGit(t, repoDir, "push", "origin", "main") + + runGit(t, repoDir, "checkout", "-b", "external", "main") + if err := os.WriteFile(filepath.Join(repoDir, "external.txt"), []byte("external\n"), 0o644); err != nil { + t.Fatal(err) + } + runGit(t, repoDir, "add", "external.txt") + runGit(t, repoDir, "commit", "-m", "external history") + runGit(t, repoDir, "push", "origin", "external") + runGit(t, repoDir, "checkout", "feature/empty") + + result, err := operator.Push(context.Background(), false, false) + if err != nil { + t.Fatalf("Push() error = %v", err) + } + if !result.Success { + t.Fatalf("Push() result = %+v, want marked base recovery to continue", result) + } + markerRef, err := gitbootstrap.MarkerRef("main") + if err != nil { + t.Fatal(err) + } + if hasLocalRef(t, repoDir, markerRef) { + t.Fatalf("bootstrap marker %q remains after crash recovery", markerRef) + } + if got := strings.TrimSpace(runGit(t, originDir, "rev-parse", "refs/heads/external")); got == "" { + t.Fatal("unrelated remote ref was lost during crash recovery") + } +} + +func TestGitOperatorPushStopsWhenEmptyRemoteGainsHistory(t *testing.T) { + repoDir, originDir, operator := setupEmptyRemoteTaskRepo(t) + seedDir := filepath.Join(filepath.Dir(originDir), "seed") + runGit(t, filepath.Dir(seedDir), "init", "-b", "external", seedDir) + runGit(t, seedDir, "config", "user.name", "External User") + runGit(t, seedDir, "config", "user.email", "external@example.com") + runGit(t, seedDir, "remote", "add", "origin", originDir) + if err := os.WriteFile(filepath.Join(seedDir, "external.txt"), []byte("external\n"), 0o644); err != nil { + t.Fatal(err) + } + runGit(t, seedDir, "add", "external.txt") + runGit(t, seedDir, "commit", "-m", "external history") + runGit(t, seedDir, "push", "origin", "external") + + result, err := operator.Push(context.Background(), false, false) + if err != nil { + t.Fatalf("Push() error = %v", err) + } + if result.Success || result.ErrorCode != emptyRemoteRemoteChangedErrorCode { + t.Fatalf("Push() result = %+v, want a remote-changed failure", result) + } + if _, err := os.Stat(filepath.Join(originDir, "refs", "heads", "feature", "empty")); !os.IsNotExist(err) { + t.Fatalf("task branch was pushed after remote race, stat error = %v", err) + } + if got := strings.TrimSpace(runGit(t, repoDir, "rev-parse", "refs/heads/main")); got == "" { + t.Fatal("local baseline was removed after remote race") + } +} + +func TestGitOperatorPushReportsEmptyRemoteBasePublicationFailure(t *testing.T) { + _, originDir, operator := setupEmptyRemoteTaskRepo(t) + writeExecutable(t, filepath.Join(originDir, "hooks", "pre-receive"), "#!/bin/sh\necho reject >&2\nexit 1\n") + + result, err := operator.Push(context.Background(), false, false) + if err != nil { + t.Fatalf("Push() error = %v", err) + } + if result.Success || result.ErrorCode != emptyRemoteBasePublishFailedErrorCode { + t.Fatalf("Push() result = %+v, want base publication failure", result) + } + if _, err := os.Stat(filepath.Join(originDir, "refs", "heads", "main")); !os.IsNotExist(err) { + t.Fatalf("base branch was published after rejection, stat error = %v", err) + } +} + +func TestGitOperatorPushReportsTaskBranchFailureAfterBasePublication(t *testing.T) { + _, originDir, operator := setupEmptyRemoteTaskRepo(t) + hook := "#!/bin/sh\nwhile read old new ref; do\n case \"$ref\" in\n refs/heads/main) exit 0 ;;\n refs/heads/feature/empty) echo reject >&2; exit 1 ;;\n esac\ndone\nexit 0\n" + writeExecutable(t, filepath.Join(originDir, "hooks", "pre-receive"), hook) + + result, err := operator.Push(context.Background(), false, false) + if err != nil { + t.Fatalf("Push() error = %v", err) + } + if result.Success || result.ErrorCode != emptyRemoteBranchPublishFailedErrorCode { + t.Fatalf("Push() result = %+v, want task branch failure", result) + } + if _, err := os.Stat(filepath.Join(originDir, "refs", "heads", "main")); err != nil { + t.Fatalf("base branch was not retained after task push failure: %v", err) + } + if _, err := os.Stat(filepath.Join(originDir, "refs", "heads", "feature", "empty")); !os.IsNotExist(err) { + t.Fatalf("task branch unexpectedly exists after rejection, stat error = %v", err) + } +} + +func TestGitOperatorPushRetainsMarkerWhenUnrelatedRefAppearsDuringBasePublication(t *testing.T) { + repoDir, originDir, operator := setupEmptyRemoteTaskRepo(t) + baseline, present, err := gitbootstrap.Validate(context.Background(), repoDir, "main") + if err != nil || !present { + t.Fatalf("Validate() = (%+v, %v, %v), want a baseline", baseline, present, err) + } + hook := "#!/bin/sh\n" + + "while read old new ref; do\n" + + " if [ \"$ref\" = \"refs/heads/main\" ] && [ \"$new\" != \"0000000000000000000000000000000000000000\" ]; then\n" + + " tree=$(printf '' | env -u GIT_OBJECT_DIRECTORY -u GIT_ALTERNATE_OBJECT_DIRECTORIES -u GIT_QUARANTINE_PATH git hash-object -t tree -w --stdin)\n" + + " commit=$(printf 'tree %s\\nauthor External User \u003cexternal@example.com\u003e 0 +0000\\ncommitter External User \u003cexternal@example.com\u003e 0 +0000\\n\\nexternal history\\n' \"$tree\" | env -u GIT_OBJECT_DIRECTORY -u GIT_ALTERNATE_OBJECT_DIRECTORIES -u GIT_QUARANTINE_PATH git hash-object -t commit -w --stdin)\n" + + " env -u GIT_OBJECT_DIRECTORY -u GIT_ALTERNATE_OBJECT_DIRECTORIES -u GIT_QUARANTINE_PATH git update-ref refs/heads/external \"$commit\"\n" + + " fi\n" + + "done\n" + + "exit 0\n" + writeExecutable(t, filepath.Join(originDir, "hooks", "pre-receive"), hook) + + result, err := operator.Push(context.Background(), false, false) + if err != nil { + t.Fatalf("Push() error = %v", err) + } + if result.Success || result.ErrorCode != emptyRemoteRemoteChangedErrorCode { + t.Fatalf("Push() result = %+v, want remote-changed failure", result) + } + markerRef, err := gitbootstrap.MarkerRef("main") + if err != nil { + t.Fatal(err) + } + if !hasLocalRef(t, repoDir, markerRef) { + t.Fatalf("bootstrap marker %q was retired after publication race", markerRef) + } + if got := strings.TrimSpace(runGit(t, originDir, "rev-parse", "refs/heads/main")); got != baseline.Commit { + t.Fatalf("remote base = %q, want the validated baseline %q", got, baseline.Commit) + } + if !hasLocalRef(t, originDir, "refs/heads/external") { + t.Fatal("unrelated remote ref was not preserved") + } + if hasLocalRef(t, originDir, "refs/heads/feature/empty") { + t.Fatal("task branch was published after publication race") + } +} + +func TestGitOperatorPushPublishesValidatedBaselineCommit(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("shell wrapper test is Unix-only") + } + + repoDir, originDir, operator := setupEmptyRemoteTaskRepo(t) + baseline, present, err := gitbootstrap.Validate(context.Background(), repoDir, "main") + if err != nil || !present { + t.Fatalf("Validate() = (%+v, %v, %v), want a baseline", baseline, present, err) + } + scriptDir := t.TempDir() + moveMarker := filepath.Join(scriptDir, "moved") + realGit, err := exec.LookPath("git") + if err != nil { + t.Fatalf("find git: %v", err) + } + shim := fmt.Sprintf("#!/bin/sh\nif [ \"$1\" = \"ls-remote\" ] && [ ! -f %q ]; then\n touch %q\n %q update-ref refs/heads/main refs/heads/feature/empty\nfi\nexec %q \"$@\"\n", moveMarker, moveMarker, realGit, realGit) + writeExecutable(t, filepath.Join(scriptDir, "git"), shim) + t.Setenv("PATH", scriptDir+string(os.PathListSeparator)+os.Getenv("PATH")) + + result, err := operator.Push(context.Background(), false, false) + if err != nil { + t.Fatalf("Push() error = %v", err) + } + if result.Success || result.ErrorCode != emptyRemoteRemoteChangedErrorCode { + t.Fatalf("Push() result = %+v, want local-baseline conflict", result) + } + if hasLocalRef(t, originDir, "refs/heads/main") { + if got := strings.TrimSpace(runGit(t, originDir, "rev-parse", "refs/heads/main")); got != baseline.Commit { + t.Fatalf("remote base = %q, want the validated baseline %q", got, baseline.Commit) + } + } + markerRef, err := gitbootstrap.MarkerRef("main") + if err != nil { + t.Fatal(err) + } + if !hasLocalRef(t, repoDir, markerRef) { + t.Fatalf("bootstrap marker %q was retired after local baseline changed", markerRef) + } + if hasLocalRef(t, originDir, "refs/heads/feature/empty") { + t.Fatal("task branch was published after local baseline changed") + } +} + +func TestGitOperatorCreatePRPublishesEmptyRemoteBaseBeforeProviderRequest(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("shell wrapper test is Unix-only") + } + _, originDir, operator := setupEmptyRemoteTaskRepo(t) + const remoteURL = "https://github.com/acme/empty.git" + + scriptDir := t.TempDir() + writeExecutable(t, filepath.Join(scriptDir, "gh"), "#!/bin/sh\nprintf 'https://github.com/acme/empty/pull/1\\n'\n") + writeGitRemoteWrapper(t, scriptDir, remoteURL) + t.Setenv("PATH", scriptDir+string(os.PathListSeparator)+os.Getenv("PATH")) + + result, err := operator.CreatePR(context.Background(), "Empty remote", "Publish the task", "main", false) + if err != nil { + t.Fatalf("CreatePR() error = %v", err) + } + if !result.Success || !result.BranchPushed || result.PRURL == "" { + t.Fatalf("CreatePR() result = %+v", result) + } + if got := strings.TrimSpace(runGit(t, originDir, "rev-parse", "refs/heads/main")); got == "" { + t.Fatal("CreatePR() did not publish the base branch") + } + if got := strings.TrimSpace(runGit(t, originDir, "rev-parse", "refs/heads/feature/empty")); got == "" { + t.Fatal("CreatePR() did not publish the task branch") + } +} + +func TestGitOperatorCreatePRRejectsDifferentBootstrapBaseBeforePush(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("shell wrapper test is Unix-only") + } + repoDir, originDir, operator := setupEmptyRemoteTaskRepo(t) + const remoteURL = "https://github.com/acme/empty.git" + + scriptDir := t.TempDir() + writeExecutable(t, filepath.Join(scriptDir, "gh"), "#!/bin/sh\nprintf 'https://github.com/acme/empty/pull/1\\n'\n") + writeGitRemoteWrapper(t, scriptDir, remoteURL) + t.Setenv("PATH", scriptDir+string(os.PathListSeparator)+os.Getenv("PATH")) + + result, err := operator.CreatePR(context.Background(), "Empty remote", "Publish the task", "develop", false) + if err != nil { + t.Fatalf("CreatePR() error = %v", err) + } + if result.Success || result.ErrorCode != emptyRemoteRemoteChangedErrorCode { + t.Fatalf("CreatePR() result = %+v, want a base mismatch before push", result) + } + if refs := strings.TrimSpace(runGit(t, repoDir, "ls-remote", "--refs", "origin")); refs != "" { + t.Fatalf("remote refs were created for a mismatched base: %s", refs) + } + if hasLocalRef(t, originDir, "refs/heads/feature/empty") { + t.Fatal("task branch was published for a mismatched base") + } +} + +func TestGitOperatorPushRedactsEmptyRemoteProbeFailure(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("shell wrapper test is Unix-only") + } + _, _, operator := setupEmptyRemoteTaskRepo(t) + const secret = "super-secret-token" + scriptDir := t.TempDir() + realGit, err := exec.LookPath("git") + if err != nil { + t.Fatalf("find git: %v", err) + } + writeExecutable(t, filepath.Join(scriptDir, "git"), fmt.Sprintf("#!/bin/sh\nif [ \"$1\" = \"ls-remote\" ]; then\n printf 'fatal: unable to access https://user:%s@example.com/empty.git: denied\\n' >&2\n exit 1\nfi\nexec %q \"$@\"\n", secret, realGit)) + t.Setenv("PATH", scriptDir+string(os.PathListSeparator)+os.Getenv("PATH")) + + result, err := operator.Push(context.Background(), false, false) + if err != nil { + t.Fatalf("Push() error = %v", err) + } + if result.Success || result.ErrorCode != emptyRemoteBasePublishFailedErrorCode { + t.Fatalf("Push() result = %+v, want bounded probe failure", result) + } + if strings.Contains(result.Error, secret) || strings.Contains(result.Output, secret) { + t.Fatalf("probe secret leaked in result: %+v", result) + } +} + +func setupEmptyRemoteTaskRepo(t *testing.T) (string, string, *GitOperator) { + t.Helper() + root := t.TempDir() + originDir := filepath.Join(root, "origin.git") + repoDir := filepath.Join(root, "repo") + runGit(t, root, "init", "--bare", "--initial-branch=main", originDir) + runGit(t, root, "init", "-b", "main", repoDir) + runGit(t, repoDir, "config", "user.name", "Task User") + runGit(t, repoDir, "config", "user.email", "task@example.com") + runGit(t, repoDir, "remote", "add", "origin", originDir) + if _, err := gitbootstrap.Ensure(context.Background(), repoDir, "main"); err != nil { + t.Fatalf("gitbootstrap.Ensure() error = %v", err) + } + runGit(t, repoDir, "checkout", "-b", "feature/empty") + if err := os.WriteFile(filepath.Join(repoDir, "change.txt"), []byte("change\n"), 0o644); err != nil { + t.Fatal(err) + } + runGit(t, repoDir, "add", "change.txt") + runGit(t, repoDir, "commit", "-m", "task change") + + tracker := NewWorkspaceTracker(repoDir, newTestLogger(t)) + tracker.SetBaseBranch("main") + return repoDir, originDir, NewGitOperator(repoDir, newTestLogger(t), tracker) +} + +func hasLocalRef(t *testing.T, repoDir, ref string) bool { + t.Helper() + cmd := exec.Command("git", "-C", repoDir, "rev-parse", "--verify", "--quiet", ref+"^{commit}") + return cmd.Run() == nil +} diff --git a/apps/backend/internal/agentctl/server/process/git_remote_contribution_resolution.go b/apps/backend/internal/agentctl/server/process/git_remote_contribution_resolution.go index 3e2f107ef1..bf3cec040f 100644 --- a/apps/backend/internal/agentctl/server/process/git_remote_contribution_resolution.go +++ b/apps/backend/internal/agentctl/server/process/git_remote_contribution_resolution.go @@ -21,7 +21,8 @@ const ( func validateContributionLeaseFlag(arg string) error { lease := strings.TrimPrefix(arg, contributionLeaseFlagPrefix) branch, expectedHead, ok := strings.Cut(lease, ":") - if !ok || strings.Contains(expectedHead, ":") || !securityutil.IsValidBranchName(branch) || !isFullCommitSHA(expectedHead) { + if !ok || strings.Contains(expectedHead, ":") || !securityutil.IsValidBranchName(branch) || + (expectedHead != "" && !isFullCommitSHA(expectedHead)) { return fmt.Errorf("potentially unsafe flag: %s", arg) } return nil diff --git a/apps/backend/internal/backendapp/adapters.go b/apps/backend/internal/backendapp/adapters.go index 9bcdca39e6..ebd5e769f1 100644 --- a/apps/backend/internal/backendapp/adapters.go +++ b/apps/backend/internal/backendapp/adapters.go @@ -266,6 +266,8 @@ func buildLifecycleLaunchRequest( PullBeforeWorktree: req.PullBeforeWorktree, RemoteSyncHandled: req.RemoteSyncHandled, RefreshRepository: req.RefreshRepository, + RefreshRepositoryWithState: req.RefreshRepositoryWithState, + RemoteRefState: req.RemoteRefState, TaskDirName: req.TaskDirName, RepoName: req.RepoName, BranchSlug: req.BranchSlug, @@ -310,30 +312,32 @@ func lifecycleRepoLaunchSpecs(repos []executor.RepoSpec) []lifecycle.RepoLaunchS specs := make([]lifecycle.RepoLaunchSpec, 0, len(repos)) for _, r := range repos { specs = append(specs, lifecycle.RepoLaunchSpec{ - TaskRepositoryID: r.TaskRepositoryID, - RepositoryID: r.RepositoryID, - RepositoryPath: r.RepositoryPath, - RepositoryURL: r.RepositoryURL, - RepoName: r.RepoName, - BaseBranch: r.BaseBranch, - DefaultBranch: r.DefaultBranch, - CheckoutBranch: r.CheckoutBranch, - PRNumber: r.PRNumber, - RemoteContribution: r.RemoteContribution, - ContributionDestination: r.ContributionDestination, - ComparisonTarget: r.ComparisonTarget, - WorktreeID: r.WorktreeID, - WorktreeBranchPrefix: r.WorktreeBranchPrefix, - WorktreeBranchTemplate: r.WorktreeBranchTemplate, - WorktreeBranchTicket: r.WorktreeBranchTicket, - PullBeforeWorktree: r.PullBeforeWorktree, - RemoteSyncHandled: r.RemoteSyncHandled, - RefreshRepository: r.RefreshRepository, - RepoSetupScript: r.RepoSetupScript, - RepoCleanupScript: r.RepoCleanupScript, - CopyFiles: r.CopyFiles, - BranchSlug: r.BranchSlug, - BranchIdentitySlug: r.BranchIdentitySlug, + TaskRepositoryID: r.TaskRepositoryID, + RepositoryID: r.RepositoryID, + RepositoryPath: r.RepositoryPath, + RepositoryURL: r.RepositoryURL, + RepoName: r.RepoName, + BaseBranch: r.BaseBranch, + DefaultBranch: r.DefaultBranch, + CheckoutBranch: r.CheckoutBranch, + PRNumber: r.PRNumber, + RemoteContribution: r.RemoteContribution, + ContributionDestination: r.ContributionDestination, + ComparisonTarget: r.ComparisonTarget, + WorktreeID: r.WorktreeID, + WorktreeBranchPrefix: r.WorktreeBranchPrefix, + WorktreeBranchTemplate: r.WorktreeBranchTemplate, + WorktreeBranchTicket: r.WorktreeBranchTicket, + PullBeforeWorktree: r.PullBeforeWorktree, + RemoteSyncHandled: r.RemoteSyncHandled, + RefreshRepository: r.RefreshRepository, + RefreshRepositoryWithState: r.RefreshRepositoryWithState, + RemoteRefState: r.RemoteRefState, + RepoSetupScript: r.RepoSetupScript, + RepoCleanupScript: r.RepoCleanupScript, + CopyFiles: r.CopyFiles, + BranchSlug: r.BranchSlug, + BranchIdentitySlug: r.BranchIdentitySlug, }) } return specs diff --git a/apps/backend/internal/common/securityutil/git.go b/apps/backend/internal/common/securityutil/git.go index ea930b50e4..ca8ec37cd0 100644 --- a/apps/backend/internal/common/securityutil/git.go +++ b/apps/backend/internal/common/securityutil/git.go @@ -112,6 +112,7 @@ func IsKnownSafeGitFlag(arg string) bool { "--amend", "--allow-empty", "--soft", "--mixed", "--hard", "--cached", "--force", "--source=HEAD", "--staged", "--worktree", "--dry-run", "--get-all", "--first-parent", "--is-ancestor", + "--refs", "--src-prefix=", "--dst-prefix=", } for _, safe := range safeFlags { diff --git a/apps/backend/internal/gitbootstrap/gitbootstrap.go b/apps/backend/internal/gitbootstrap/gitbootstrap.go new file mode 100644 index 0000000000..1a3cc44ad2 --- /dev/null +++ b/apps/backend/internal/gitbootstrap/gitbootstrap.go @@ -0,0 +1,265 @@ +// Package gitbootstrap creates and validates Kandev's local baseline for an +// authenticated remote that has no refs yet. +package gitbootstrap + +import ( + "context" + "errors" + "fmt" + "os" + "strings" + + "github.com/kandev/kandev/internal/common/securityutil" + "github.com/kandev/kandev/internal/common/subproc" +) + +const ( + // EmptyTreeSHA is the empty tree object in the default SHA-1 Git object + // format. Repositories using another object format still receive the + // repository's own empty-tree object from git mktree. + EmptyTreeSHA = "4b825dc642cb6eb9a060e54bf8d69288fbee4904" + markerPrefix = "refs/kandev/empty-remote/" + commitMessage = "Kandev empty remote baseline" + identityName = "Kandev" + identityEmail = "kandev@localhost" + commitDate = "1970-01-01T00:00:00Z" +) + +var ( + ErrInvalidBaseBranch = errors.New("invalid empty-remote base branch") + ErrBaselineConflict = errors.New("empty-remote baseline conflicts with local Git history") +) + +// Baseline identifies the local commit and refs that represent an empty +// remote. The marker and base refs must always point at the same commit. +type Baseline struct { + Commit string + BaseRef string + MarkerRef string +} + +// MarkerRef returns the local marker ref for a validated base branch. +func MarkerRef(baseBranch string) (string, error) { + branch, err := normalizeBranch(baseBranch) + if err != nil { + return "", err + } + return markerPrefix + branch, nil +} + +// Ensure creates the deterministic local baseline when neither local ref +// exists. It never writes files or contacts the remote. A concurrent local +// history write is reported as a conflict and is never overwritten. +func Ensure(ctx context.Context, repoPath, baseBranch string) (Baseline, error) { + baseRef, markerRef, err := refsForBranch(baseBranch) + if err != nil { + return Baseline{}, err + } + existing, present, err := readBaseline(ctx, repoPath, baseRef, markerRef) + if err != nil { + return Baseline{}, err + } + if present { + return existing, nil + } + if basePresent, err := refPresent(ctx, repoPath, baseRef); err != nil { + return Baseline{}, err + } else if basePresent { + return Baseline{}, ErrBaselineConflict + } + + tree, err := createEmptyTree(ctx, repoPath) + if err != nil { + return Baseline{}, fmt.Errorf("create empty Git tree: %w", err) + } + commit, err := createCommit(ctx, repoPath, tree) + if err != nil { + return Baseline{}, fmt.Errorf("create empty-remote baseline commit: %w", err) + } + baseline := Baseline{Commit: commit, BaseRef: baseRef, MarkerRef: markerRef} + if err := createRefs(ctx, repoPath, baseline); err != nil { + verified, verifiedPresent, verifyErr := readBaseline(ctx, repoPath, baseRef, markerRef) + if verifyErr == nil && verifiedPresent && verified.Commit == commit { + return verified, nil + } + if verifyErr != nil { + return Baseline{}, fmt.Errorf("publish local empty-remote refs: %w; verify race: %v", err, verifyErr) + } + if verifiedPresent { + return Baseline{}, ErrBaselineConflict + } + return Baseline{}, fmt.Errorf("publish local empty-remote refs: %w", err) + } + return baseline, nil +} + +// Validate reports whether the exact local baseline marker exists. A missing +// marker is not an error because it means this repository is not bootstrapped. +func Validate(ctx context.Context, repoPath, baseBranch string) (Baseline, bool, error) { + baseRef, markerRef, err := refsForBranch(baseBranch) + if err != nil { + return Baseline{}, false, err + } + baseline, present, err := readBaseline(ctx, repoPath, baseRef, markerRef) + return baseline, present, err +} + +// Retire removes the local bootstrap marker after the baseline has been +// published. The expected commit protects a concurrent local ref change. +func Retire(ctx context.Context, repoPath string, baseline Baseline) error { + if strings.TrimSpace(baseline.MarkerRef) == "" || strings.TrimSpace(baseline.Commit) == "" { + return errors.New("invalid empty-remote baseline marker") + } + input := strings.Join([]string{ + "start", + "delete " + baseline.MarkerRef + " " + baseline.Commit, + "prepare", + "commit", + "", + }, "\n") + if _, err := runGitWithInput(ctx, repoPath, input, "update-ref", "--stdin"); err != nil { + return fmt.Errorf("retire empty-remote baseline marker: %w", err) + } + return nil +} + +func refsForBranch(baseBranch string) (string, string, error) { + branch, err := normalizeBranch(baseBranch) + if err != nil { + return "", "", err + } + return "refs/heads/" + branch, markerPrefix + branch, nil +} + +func normalizeBranch(baseBranch string) (string, error) { + branch := strings.TrimPrefix(strings.TrimSpace(baseBranch), "origin/") + if !securityutil.IsValidBaseBranchRef(branch) { + return "", fmt.Errorf("%w: %q", ErrInvalidBaseBranch, baseBranch) + } + return branch, nil +} + +func readBaseline(ctx context.Context, repoPath, baseRef, markerRef string) (Baseline, bool, error) { + baseCommit, basePresent, err := readRef(ctx, repoPath, baseRef) + if err != nil { + return Baseline{}, false, err + } + markerCommit, markerPresent, err := readRef(ctx, repoPath, markerRef) + if err != nil { + return Baseline{}, false, err + } + if !markerPresent { + return Baseline{}, false, nil + } + if !basePresent || !markerPresent || baseCommit != markerCommit { + return Baseline{}, false, ErrBaselineConflict + } + return Baseline{Commit: baseCommit, BaseRef: baseRef, MarkerRef: markerRef}, true, nil +} + +func refPresent(ctx context.Context, repoPath, ref string) (bool, error) { + _, present, err := readRef(ctx, repoPath, ref) + return present, err +} + +func readRef(ctx context.Context, repoPath, ref string) (string, bool, error) { + output, err := runGit(ctx, repoPath, "rev-parse", "--verify", "--quiet", ref+"^{commit}") + if err != nil { + if strings.TrimSpace(output) == "" { + return "", false, nil + } + return "", false, fmt.Errorf("read local Git ref %q: %w", ref, err) + } + commit := strings.TrimSpace(output) + if commit == "" { + return "", false, nil + } + return commit, true, nil +} + +func createEmptyTree(ctx context.Context, repoPath string) (string, error) { + output, err := runGitWithInput(ctx, repoPath, "", "mktree") + if err != nil { + return "", err + } + tree := strings.TrimSpace(output) + if tree == "" { + return "", errors.New("git mktree returned no object ID") + } + return tree, nil +} + +func createCommit(ctx context.Context, repoPath, tree string) (string, error) { + cmd := subproc.NewGitCommand(ctx, + "-C", repoPath, + "-c", "user.name="+identityName, + "-c", "user.email="+identityEmail, + "-c", "commit.gpgSign=false", + "commit-tree", tree, "-m", commitMessage, + ) + cmd.Env = baselineGitEnvironment() + output, err := subproc.RunGitCombinedOutputClass(ctx, subproc.GitLifecycle, cmd) + if err != nil { + return "", fmt.Errorf("%s: %w", strings.TrimSpace(string(output)), err) + } + commit := strings.TrimSpace(string(output)) + if commit == "" { + return "", errors.New("git commit-tree returned no object ID") + } + return commit, nil +} + +func baselineGitEnvironment() []string { + const ( + authorName = "GIT_AUTHOR_NAME=" + authorEmail = "GIT_AUTHOR_EMAIL=" + committerName = "GIT_COMMITTER_NAME=" + committerEmail = "GIT_COMMITTER_EMAIL=" + ) + env := make([]string, 0, len(os.Environ())+6) + for _, entry := range os.Environ() { + if strings.HasPrefix(entry, authorName) || strings.HasPrefix(entry, authorEmail) || + strings.HasPrefix(entry, committerName) || strings.HasPrefix(entry, committerEmail) { + continue + } + env = append(env, entry) + } + return append(env, + "GIT_AUTHOR_DATE="+commitDate, + "GIT_COMMITTER_DATE="+commitDate, + "GIT_AUTHOR_NAME="+identityName, + "GIT_AUTHOR_EMAIL="+identityEmail, + "GIT_COMMITTER_NAME="+identityName, + "GIT_COMMITTER_EMAIL="+identityEmail, + "GIT_CONFIG_NOSYSTEM=1", + "GIT_TERMINAL_PROMPT=0", + ) +} + +func createRefs(ctx context.Context, repoPath string, baseline Baseline) error { + input := strings.Join([]string{ + "start", + "create " + baseline.BaseRef + " " + baseline.Commit, + "create " + baseline.MarkerRef + " " + baseline.Commit, + "prepare", + "commit", + "", + }, "\n") + _, err := runGitWithInput(ctx, repoPath, input, "update-ref", "--stdin") + return err +} + +func runGitWithInput(ctx context.Context, repoPath, input string, args ...string) (string, error) { + cmd := subproc.NewGitCommand(ctx, append([]string{"-C", repoPath}, args...)...) + cmd.Stdin = strings.NewReader(input) + cmd.Env = append(os.Environ(), "GIT_CONFIG_NOSYSTEM=1", "GIT_TERMINAL_PROMPT=0") + output, err := subproc.RunGitCombinedOutputClass(ctx, subproc.GitLifecycle, cmd) + if err != nil { + return string(output), fmt.Errorf("git %v: %s: %w", args, strings.TrimSpace(string(output)), err) + } + return string(output), nil +} + +func runGit(ctx context.Context, repoPath string, args ...string) (string, error) { + return runGitWithInput(ctx, repoPath, "", args...) +} diff --git a/apps/backend/internal/gitbootstrap/gitbootstrap_test.go b/apps/backend/internal/gitbootstrap/gitbootstrap_test.go new file mode 100644 index 0000000000..0412bfa3b4 --- /dev/null +++ b/apps/backend/internal/gitbootstrap/gitbootstrap_test.go @@ -0,0 +1,80 @@ +package gitbootstrap_test + +import ( + "context" + "os/exec" + "path/filepath" + "strings" + "testing" + + "github.com/kandev/kandev/internal/gitbootstrap" +) + +func TestEnsureCreatesDeterministicEmptyBaseline(t *testing.T) { + t.Setenv("GIT_AUTHOR_NAME", "Inherited Author") + t.Setenv("GIT_AUTHOR_EMAIL", "inherited-author@example.com") + t.Setenv("GIT_COMMITTER_NAME", "Inherited Committer") + t.Setenv("GIT_COMMITTER_EMAIL", "inherited-committer@example.com") + + repoPath := t.TempDir() + runGit(t, repoPath, "init", "-b", "main", ".") + + first, err := gitbootstrap.Ensure(context.Background(), repoPath, "main") + if err != nil { + t.Fatalf("Ensure() error = %v", err) + } + if first.Commit == "" { + t.Fatal("Ensure() returned an empty baseline commit") + } + if got := strings.TrimSpace(runGit(t, repoPath, "rev-parse", "refs/heads/main")); got != first.Commit { + t.Fatalf("base branch = %q, want %q", got, first.Commit) + } + if got := strings.TrimSpace(runGit(t, repoPath, "rev-parse", first.MarkerRef)); got != first.Commit { + t.Fatalf("marker = %q, want %q", got, first.Commit) + } + if got := strings.TrimSpace(runGit(t, repoPath, "rev-parse", first.Commit+"^{tree}")); got != gitbootstrap.EmptyTreeSHA { + t.Fatalf("baseline tree = %q, want empty tree %q", got, gitbootstrap.EmptyTreeSHA) + } + entries, err := filepath.Glob(filepath.Join(repoPath, "*")) + if err != nil { + t.Fatalf("list repository files: %v", err) + } + for _, entry := range entries { + if filepath.Base(entry) != ".git" { + t.Fatalf("baseline created working-tree files: %v", entries) + } + } + + second, err := gitbootstrap.Ensure(context.Background(), repoPath, "main") + if err != nil { + t.Fatalf("second Ensure() error = %v", err) + } + if second.Commit != first.Commit { + t.Fatalf("second baseline commit = %q, want deterministic %q", second.Commit, first.Commit) + } + + t.Setenv("GIT_AUTHOR_NAME", "Another Author") + t.Setenv("GIT_AUTHOR_EMAIL", "another-author@example.com") + t.Setenv("GIT_COMMITTER_NAME", "Another Committer") + t.Setenv("GIT_COMMITTER_EMAIL", "another-committer@example.com") + otherRepo := t.TempDir() + runGit(t, otherRepo, "init", "-b", "main", ".") + other, err := gitbootstrap.Ensure(context.Background(), otherRepo, "main") + if err != nil { + t.Fatalf("Ensure() with another inherited identity error = %v", err) + } + if other.Commit != first.Commit { + t.Fatalf("baseline changed with inherited Git identity: first=%q other=%q", first.Commit, other.Commit) + } +} + +func runGit(t *testing.T, repoPath string, args ...string) string { + t.Helper() + cmd := exec.Command("git", args...) + cmd.Dir = repoPath + output, err := cmd.CombinedOutput() + if err != nil { + t.Fatalf("git %v: %v\n%s", args, err, output) + } + return string(output) +} diff --git a/apps/backend/internal/orchestrator/executor/executor.go b/apps/backend/internal/orchestrator/executor/executor.go index 92e4721950..1f18b69818 100644 --- a/apps/backend/internal/orchestrator/executor/executor.go +++ b/apps/backend/internal/orchestrator/executor/executor.go @@ -442,6 +442,10 @@ type LaunchAgentRequest struct { // RefreshRepository is an optional provider-authenticated refresh deferred // until worktree materialization. A valid reusable worktree bypasses it. RefreshRepository func(context.Context) error + // RefreshRepositoryWithState is the typed refresh path used to distinguish + // an authenticated empty remote from an unknown refresh result. + RefreshRepositoryWithState func(context.Context) (repoclone.RemoteRefState, error) + RemoteRefState repoclone.RemoteRefState // Task directory mode: place worktree at ~/.kandev/tasks/{TaskDirName}/{RepoName}/ TaskDirName string // Semantic task directory name (e.g. "fix-bug_ab12") @@ -492,10 +496,12 @@ type RepoSpec struct { RemoteSyncHandled bool // RefreshRepository is an optional provider-authenticated refresh deferred // until worktree materialization. A valid reusable worktree bypasses it. - RefreshRepository func(context.Context) error - RepoSetupScript string - RepoCleanupScript string - CopyFiles string + RefreshRepository func(context.Context) error + RefreshRepositoryWithState func(context.Context) (repoclone.RemoteRefState, error) + RemoteRefState repoclone.RemoteRefState + RepoSetupScript string + RepoCleanupScript string + CopyFiles string // BranchSlug, when non-empty, suffixes the repo dir so the same repo can // host multiple branch worktrees as siblings within one task. Set by the // orchestrator when buildRepoSpecs detects multiple rows sharing a @@ -893,39 +899,89 @@ type strictAuthenticatedRepoCloner interface { ) error } +type remoteStateRepoCloner interface { + EnsureWorkspaceClonedWithCredentialRequestAndState( + ctx context.Context, request repoclone.GitCredentialRequest, + credentialHost, token string, + ) (string, repoclone.RemoteRefState, error) + RefreshWorkspaceRepositoryWithCredentialRequestAndState( + ctx context.Context, request repoclone.GitCredentialRequest, + repositoryPath, credentialHost, token string, + ) (repoclone.RemoteRefState, error) +} + +type remoteStateAuthenticatedRepoCloner interface { + EnsureWorkspaceClonedWithBasicAuthAndState( + ctx context.Context, workspaceID, provider, providerHost, + cloneURL, owner, name, username, password string, + ) (string, repoclone.RemoteRefState, error) + RefreshWorkspaceRepositoryWithBasicAuthAndState( + ctx context.Context, workspaceID, provider, providerHost, + cloneURL, owner, name, repositoryPath, username, password string, + ) (repoclone.RemoteRefState, error) +} + +type localRemoteStateRepoCloner interface { + InspectLocalRepositoryRemoteRefState( + ctx context.Context, repositoryPath string, + ) (repoclone.RemoteRefState, error) +} + const providerAzureDevOps = "azure_devops" func (e *Executor) ensureClonedWithWorkspaceAuth( ctx context.Context, repo *models.Repository, cloneURL string, ) (string, error) { - return e.ensureClonedWithWorkspaceAuthForSession(ctx, "", "", repo, cloneURL) + path, _, err := e.ensureClonedWithWorkspaceAuthForSessionAndState(ctx, "", "", repo, cloneURL) + return path, err } func (e *Executor) ensureClonedWithWorkspaceAuthForSession( ctx context.Context, taskID, sessionID string, repo *models.Repository, cloneURL string, ) (string, error) { + path, _, err := e.ensureClonedWithWorkspaceAuthForSessionAndState(ctx, taskID, sessionID, repo, cloneURL) + return path, err +} + +func (e *Executor) ensureClonedWithWorkspaceAuthForSessionAndState( + ctx context.Context, taskID, sessionID string, repo *models.Repository, cloneURL string, +) (string, repoclone.RemoteRefState, error) { credentialHost, token := "", "" if strings.EqualFold(repo.Provider, "gitlab") && e.gitlabCredentials != nil { credentialHost, token, _ = e.gitlabCredentials.ResolveGitLabExecutionCredentials(ctx, repo.WorkspaceID) } if repo.Provider != providerAzureDevOps || !strings.HasPrefix(cloneURL, "https://") { - return e.repoCloner.EnsureWorkspaceClonedWithCredentialRequest( - ctx, repositoryGitCredentialRequest(taskID, sessionID, repo, cloneURL), credentialHost, token, + request := repositoryGitCredentialRequest(taskID, sessionID, repo, cloneURL) + if stateCloner, ok := e.repoCloner.(remoteStateRepoCloner); ok { + return stateCloner.EnsureWorkspaceClonedWithCredentialRequestAndState( + ctx, request, credentialHost, token, + ) + } + path, err := e.repoCloner.EnsureWorkspaceClonedWithCredentialRequest( + ctx, request, credentialHost, token, ) + return path, repoclone.RemoteRefStateHasRefs, err } authCloner, ok := e.repoCloner.(authenticatedRepoCloner) if !ok || e.secretStore == nil { - return "", fmt.Errorf("azure DevOps repository clone authentication is unavailable") + return "", repoclone.RemoteRefStateUnknown, fmt.Errorf("azure DevOps repository clone authentication is unavailable") } pat, err := e.secretStore.Reveal(ctx, cloneauth.AzureDevOpsPATKey(repo.WorkspaceID)) if err != nil { - return "", fmt.Errorf("read Azure DevOps clone credential: %w", err) + return "", repoclone.RemoteRefStateUnknown, fmt.Errorf("read Azure DevOps clone credential: %w", err) } // Azure DevOps PAT authentication ignores the username; any non-empty value works. - return authCloner.EnsureWorkspaceClonedWithBasicAuth( + if stateCloner, ok := e.repoCloner.(remoteStateAuthenticatedRepoCloner); ok { + return stateCloner.EnsureWorkspaceClonedWithBasicAuthAndState( + ctx, repo.WorkspaceID, repo.Provider, repo.ProviderHost, + cloneURL, repo.ProviderOwner, repo.ProviderName, "kandev", pat, + ) + } + path, err := authCloner.EnsureWorkspaceClonedWithBasicAuth( ctx, repo.WorkspaceID, repo.Provider, repo.ProviderHost, cloneURL, repo.ProviderOwner, repo.ProviderName, "kandev", pat, ) + return path, repoclone.RemoteRefStateHasRefs, err } func repositoryGitCredentialRequest( diff --git a/apps/backend/internal/orchestrator/executor/executor_environment_reuse.go b/apps/backend/internal/orchestrator/executor/executor_environment_reuse.go index 5bff0f0017..f44ffbfbc3 100644 --- a/apps/backend/internal/orchestrator/executor/executor_environment_reuse.go +++ b/apps/backend/internal/orchestrator/executor/executor_environment_reuse.go @@ -318,24 +318,26 @@ func topLevelLaunchRepoSpec(req *LaunchAgentRequest) (RepoSpec, bool) { return RepoSpec{}, false } return RepoSpec{ - TaskRepositoryID: req.TaskRepositoryID, - RepositoryID: req.RepositoryID, - RepositoryPath: req.RepositoryPath, - RepositoryURL: req.RepositoryURL, - RepoName: req.RepoName, - BaseBranch: req.BaseBranch, - DefaultBranch: req.DefaultBranch, - CheckoutBranch: req.CheckoutBranch, - PRNumber: req.PRNumber, - WorktreeID: req.WorktreeID, - WorktreeBranchPrefix: req.WorktreeBranchPrefix, - WorktreeBranchTemplate: req.WorktreeBranchTemplate, - WorktreeBranchTicket: req.WorktreeBranchTicket, - PullBeforeWorktree: req.PullBeforeWorktree, - RemoteSyncHandled: req.RemoteSyncHandled, - RefreshRepository: req.RefreshRepository, - CopyFiles: req.CopyFiles, - BranchIdentitySlug: topLevelBranchIdentitySlug(req), + TaskRepositoryID: req.TaskRepositoryID, + RepositoryID: req.RepositoryID, + RepositoryPath: req.RepositoryPath, + RepositoryURL: req.RepositoryURL, + RepoName: req.RepoName, + BaseBranch: req.BaseBranch, + DefaultBranch: req.DefaultBranch, + CheckoutBranch: req.CheckoutBranch, + PRNumber: req.PRNumber, + WorktreeID: req.WorktreeID, + WorktreeBranchPrefix: req.WorktreeBranchPrefix, + WorktreeBranchTemplate: req.WorktreeBranchTemplate, + WorktreeBranchTicket: req.WorktreeBranchTicket, + PullBeforeWorktree: req.PullBeforeWorktree, + RemoteSyncHandled: req.RemoteSyncHandled, + RefreshRepository: req.RefreshRepository, + RefreshRepositoryWithState: req.RefreshRepositoryWithState, + RemoteRefState: req.RemoteRefState, + CopyFiles: req.CopyFiles, + BranchIdentitySlug: topLevelBranchIdentitySlug(req), }, true } diff --git a/apps/backend/internal/orchestrator/executor/executor_execute.go b/apps/backend/internal/orchestrator/executor/executor_execute.go index cb5ab253b1..f2cacff73b 100644 --- a/apps/backend/internal/orchestrator/executor/executor_execute.go +++ b/apps/backend/internal/orchestrator/executor/executor_execute.go @@ -1768,20 +1768,22 @@ func buildRepoSpecs(allRepos []*repoInfo) []RepoSpec { out := make([]RepoSpec, 0, len(allRepos)) for _, info := range allRepos { spec := RepoSpec{ - TaskRepositoryID: info.TaskRepositoryID, - RepositoryID: info.RepositoryID, - RepositoryPath: info.RepositoryPath, - BaseBranch: info.BaseBranch, - CheckoutBranch: info.CheckoutBranch, - PRNumber: info.PRNumber, - RemoteContribution: info.RemoteContribution, - ContributionDestination: info.ContributionDestination, - ComparisonTarget: info.ComparisonTarget, - WorktreeBranchPrefix: info.WorktreeBranchPrefix, - WorktreeBranchTemplate: info.WorktreeBranchTemplate, - PullBeforeWorktree: info.PullBeforeWorktree, - RemoteSyncHandled: info.RemoteSyncHandled, - RefreshRepository: info.RefreshRepository, + TaskRepositoryID: info.TaskRepositoryID, + RepositoryID: info.RepositoryID, + RepositoryPath: info.RepositoryPath, + BaseBranch: info.BaseBranch, + CheckoutBranch: info.CheckoutBranch, + PRNumber: info.PRNumber, + RemoteContribution: info.RemoteContribution, + ContributionDestination: info.ContributionDestination, + ComparisonTarget: info.ComparisonTarget, + WorktreeBranchPrefix: info.WorktreeBranchPrefix, + WorktreeBranchTemplate: info.WorktreeBranchTemplate, + PullBeforeWorktree: info.PullBeforeWorktree, + RemoteSyncHandled: info.RemoteSyncHandled, + RefreshRepository: info.RefreshRepository, + RefreshRepositoryWithState: info.RefreshRepositoryWithState, + RemoteRefState: info.RemoteRefState, } if info.Repository != nil { spec.RepoName = info.Repository.Name @@ -1853,6 +1855,8 @@ func (e *Executor) applyRepositoryConfig(req *LaunchAgentRequest, task *v1.Task, req.PullBeforeWorktree = repoInfo.PullBeforeWorktree req.RemoteSyncHandled = repoInfo.RemoteSyncHandled req.RefreshRepository = repoInfo.RefreshRepository + req.RefreshRepositoryWithState = repoInfo.RefreshRepositoryWithState + req.RemoteRefState = repoInfo.RemoteRefState if repoInfo.Repository != nil { req.DefaultBranch = repoInfo.Repository.DefaultBranch if req.UseWorktree { diff --git a/apps/backend/internal/orchestrator/executor/executor_resume.go b/apps/backend/internal/orchestrator/executor/executor_resume.go index 0341f15e65..51091cf543 100644 --- a/apps/backend/internal/orchestrator/executor/executor_resume.go +++ b/apps/backend/internal/orchestrator/executor/executor_resume.go @@ -63,22 +63,24 @@ func isTerminalSessionState(state models.TaskSessionState) bool { // repoInfo holds resolved repository details for agent launch. type repoInfo struct { - TaskRepositoryID string - RepositoryID string - RepositoryPath string - BaseBranch string - CheckoutBranch string - PRNumber int // GitHub PR number when CheckoutBranch is a PR head; sourced from task_repositories.metadata["pr_number"]. - RemoteContribution *models.RemoteContribution - ContributionDestination *models.ContributionDestination - ComparisonTarget *models.ComparisonTarget - Position int - WorktreeBranchPrefix string - WorktreeBranchTemplate string - PullBeforeWorktree bool - RemoteSyncHandled bool - RefreshRepository func(context.Context) error - Repository *models.Repository + TaskRepositoryID string + RepositoryID string + RepositoryPath string + BaseBranch string + CheckoutBranch string + PRNumber int // GitHub PR number when CheckoutBranch is a PR head; sourced from task_repositories.metadata["pr_number"]. + RemoteContribution *models.RemoteContribution + ContributionDestination *models.ContributionDestination + ComparisonTarget *models.ComparisonTarget + Position int + WorktreeBranchPrefix string + WorktreeBranchTemplate string + PullBeforeWorktree bool + RemoteSyncHandled bool + RefreshRepository func(context.Context) error + RefreshRepositoryWithState func(context.Context) (repoclone.RemoteRefState, error) + RemoteRefState repoclone.RemoteRefState + Repository *models.Repository } // resumeCredentialSnapshotBackup holds the non-secret routing metadata that @@ -205,9 +207,11 @@ func (e *Executor) resolveTaskRepoInfoForSession( return nil, err } - if err := e.ensureRepoLocalPathForSession(ctx, tr.TaskID, sessionID, repo); err != nil { + remoteRefState, err := e.ensureRepoLocalPathForSessionAndState(ctx, tr.TaskID, sessionID, repo) + if err != nil { return nil, err } + info.RemoteRefState = remoteRefState // Backfill default_branch from the local clone when missing. This fires for // two cases: (1) a freshly cloned provider-backed repo whose row was created @@ -243,6 +247,11 @@ func (e *Executor) resolveTaskRepoInfoForSession( refreshCtx, tr.TaskID, sessionID, repo, prNumber, checkoutBranch, ) } + info.RefreshRepositoryWithState = func(refreshCtx context.Context) (repoclone.RemoteRefState, error) { + return e.refreshManagedRepositoryForSessionWithState( + refreshCtx, tr.TaskID, sessionID, repo, prNumber, checkoutBranch, + ) + } } return info, nil } @@ -297,8 +306,17 @@ func isPluginManagedRepository(repo *models.Repository) bool { func (e *Executor) refreshManagedRepositoryForSession( ctx context.Context, taskID, sessionID string, repo *models.Repository, prNumber int, checkoutBranch string, ) error { + _, err := e.refreshManagedRepositoryForSessionWithState( + ctx, taskID, sessionID, repo, prNumber, checkoutBranch, + ) + return err +} + +func (e *Executor) refreshManagedRepositoryForSessionWithState( + ctx context.Context, taskID, sessionID string, repo *models.Repository, prNumber int, checkoutBranch string, +) (repoclone.RemoteRefState, error) { if e.repoCloner == nil || repo.LocalPath == "" { - return errors.New("managed repository refresh is unavailable") + return repoclone.RemoteRefStateUnknown, errors.New("managed repository refresh is unavailable") } cloneURL := repositoryCloneURL(repo) if cloneURL == "" { @@ -307,7 +325,7 @@ func (e *Executor) refreshManagedRepositoryForSession( ctx, repo.Provider, repo.ProviderHost, repo.ProviderOwner, repo.ProviderName, ) if err != nil || cloneURL == "" { - return ErrNoCloneURL + return repoclone.RemoteRefStateUnknown, ErrNoCloneURL } } credentialOrigin, token := "", "" @@ -316,11 +334,11 @@ func (e *Executor) refreshManagedRepositoryForSession( var err error credentialOrigin, token, err = e.gitlabCredentials.ResolveGitLabExecutionCredentials(ctx, repo.WorkspaceID) if err != nil { - return fmt.Errorf("resolve GitLab refresh credentials: %w", err) + return repoclone.RemoteRefStateUnknown, fmt.Errorf("resolve GitLab refresh credentials: %w", err) } } if provider == providerAzureDevOps && strings.HasPrefix(strings.ToLower(cloneURL), "https://") { - return e.refreshAzureDevOpsRepositoryForSession( + return e.refreshAzureDevOpsRepositoryForSessionWithState( ctx, repo, cloneURL, ) } @@ -329,32 +347,58 @@ func (e *Executor) refreshManagedRepositoryForSession( request.PRNumber = prNumber request.CheckoutBranch = checkoutBranch } + if stateCloner, ok := e.repoCloner.(remoteStateRepoCloner); ok { + state, err := stateCloner.RefreshWorkspaceRepositoryWithCredentialRequestAndState( + ctx, request, repo.LocalPath, credentialOrigin, token, + ) + if err != nil { + return repoclone.RemoteRefStateUnknown, fmt.Errorf("refresh repository before worktree: %w", err) + } + return state, nil + } if err := e.repoCloner.RefreshWorkspaceRepositoryWithCredentialRequest( ctx, request, repo.LocalPath, credentialOrigin, token, ); err != nil { - return fmt.Errorf("refresh repository before worktree: %w", err) + return repoclone.RemoteRefStateUnknown, fmt.Errorf("refresh repository before worktree: %w", err) } - return nil + return repoclone.RemoteRefStateHasRefs, nil } func (e *Executor) refreshAzureDevOpsRepositoryForSession( ctx context.Context, repo *models.Repository, cloneURL string, ) error { + _, err := e.refreshAzureDevOpsRepositoryForSessionWithState(ctx, repo, cloneURL) + return err +} + +func (e *Executor) refreshAzureDevOpsRepositoryForSessionWithState( + ctx context.Context, repo *models.Repository, cloneURL string, +) (repoclone.RemoteRefState, error) { authCloner, ok := e.repoCloner.(strictAuthenticatedRepoCloner) if !ok || e.secretStore == nil { - return errors.New("azure DevOps repository refresh authentication is unavailable") + return repoclone.RemoteRefStateUnknown, errors.New("azure DevOps repository refresh authentication is unavailable") } pat, err := e.secretStore.Reveal(ctx, cloneauth.AzureDevOpsPATKey(repo.WorkspaceID)) if err != nil { - return fmt.Errorf("read Azure DevOps refresh credential: %w", err) + return repoclone.RemoteRefStateUnknown, fmt.Errorf("read Azure DevOps refresh credential: %w", err) + } + if stateCloner, ok := e.repoCloner.(remoteStateAuthenticatedRepoCloner); ok { + state, err := stateCloner.RefreshWorkspaceRepositoryWithBasicAuthAndState( + ctx, repo.WorkspaceID, repo.Provider, repo.ProviderHost, cloneURL, + repo.ProviderOwner, repo.ProviderName, repo.LocalPath, "kandev", pat, + ) + if err != nil { + return repoclone.RemoteRefStateUnknown, fmt.Errorf("refresh Azure DevOps repository before worktree: %w", err) + } + return state, nil } if err := authCloner.RefreshWorkspaceRepositoryWithBasicAuth( ctx, repo.WorkspaceID, repo.Provider, repo.ProviderHost, cloneURL, repo.ProviderOwner, repo.ProviderName, repo.LocalPath, "kandev", pat, ); err != nil { - return fmt.Errorf("refresh Azure DevOps repository before worktree: %w", err) + return repoclone.RemoteRefStateUnknown, fmt.Errorf("refresh Azure DevOps repository before worktree: %w", err) } - return nil + return repoclone.RemoteRefStateHasRefs, nil } // ensureRepoLocalPath re-clones a repo's local checkout in place when it's @@ -374,21 +418,49 @@ func (e *Executor) ensureRepoLocalPath(ctx context.Context, repo *models.Reposit func (e *Executor) ensureRepoLocalPathForSession( ctx context.Context, taskID, sessionID string, repo *models.Repository, ) error { - if repo.SourceType == sourceTypeLocal || !hasProviderRepositoryIdentity(repo) { - return nil + _, err := e.ensureRepoLocalPathForSessionAndState(ctx, taskID, sessionID, repo) + return err +} + +func (e *Executor) ensureRepoLocalPathForSessionAndState( + ctx context.Context, taskID, sessionID string, repo *models.Repository, +) (repoclone.RemoteRefState, error) { + if repo.SourceType == sourceTypeLocal { + if repo.LocalPath == "" || e.repoCloner == nil { + return repoclone.RemoteRefStateUnknown, nil + } + stateCloner, ok := e.repoCloner.(localRemoteStateRepoCloner) + if !ok { + return repoclone.RemoteRefStateUnknown, nil + } + state, err := stateCloner.InspectLocalRepositoryRemoteRefState(ctx, repo.LocalPath) + if err != nil { + // Local repositories historically support offline launch. Preserve + // that behavior when an origin is missing or temporarily + // unreachable; unknown state never authorizes empty-remote bootstrap. + e.logger.Debug("could not inspect local repository remote refs", + zap.String("repository_id", repo.ID), + zap.String("local_path", repo.LocalPath), + zap.Error(err)) + return repoclone.RemoteRefStateUnknown, nil + } + return state, nil + } + if !hasProviderRepositoryIdentity(repo) { + return repoclone.RemoteRefStateUnknown, nil } if repo.LocalPath != "" && isLocalGitRepo(repo.LocalPath) && (e.repoCloner == nil || !e.repoCloner.ShouldRecloneForWorkspace(repo.WorkspaceID, repo.LocalPath)) { - return e.reconcileGitHubCheckoutOrigin(ctx, repo, repo.LocalPath) + return repoclone.RemoteRefStateUnknown, e.reconcileGitHubCheckoutOrigin(ctx, repo, repo.LocalPath) } - localPath, cloneErr := e.ensureRepoClonedForSession(ctx, taskID, sessionID, repo) + localPath, state, cloneErr := e.ensureRepoClonedForSessionAndState(ctx, taskID, sessionID, repo) if cloneErr != nil { - return cloneErr + return state, cloneErr } if localPath != "" { repo.LocalPath = localPath } - return nil + return state, nil } // ensureRepoCloned clones a provider-backed repository to local disk and updates its local path in the database. @@ -400,13 +472,20 @@ func (e *Executor) ensureRepoCloned(ctx context.Context, repo *models.Repository func (e *Executor) ensureRepoClonedForSession( ctx context.Context, taskID, sessionID string, repo *models.Repository, ) (string, error) { + path, _, err := e.ensureRepoClonedForSessionAndState(ctx, taskID, sessionID, repo) + return path, err +} + +func (e *Executor) ensureRepoClonedForSessionAndState( + ctx context.Context, taskID, sessionID string, repo *models.Repository, +) (string, repoclone.RemoteRefState, error) { if e.repoCloner == nil { e.logger.Warn("repository has no local path and no cloner configured", zap.String("repository_id", repo.ID), zap.String("provider", repo.Provider), zap.String("owner", repo.ProviderOwner), zap.String("name", repo.ProviderName)) - return "", nil + return "", repoclone.RemoteRefStateUnknown, nil } // RemoteURL is the canonical provider-declared transport. In particular, @@ -419,7 +498,7 @@ func (e *Executor) ensureRepoClonedForSession( ctx, repo.Provider, repo.ProviderHost, repo.ProviderOwner, repo.ProviderName, ) if urlErr != nil || cloneURL == "" { - return "", ErrNoCloneURL + return "", repoclone.RemoteRefStateUnknown, ErrNoCloneURL } } @@ -427,13 +506,13 @@ func (e *Executor) ensureRepoClonedForSession( zap.String("repository_id", repo.ID), zap.String("repo", repo.ProviderOwner+"/"+repo.ProviderName)) - localPath, err := e.ensureClonedWithWorkspaceAuthForSession(ctx, taskID, sessionID, repo, cloneURL) + localPath, state, err := e.ensureClonedWithWorkspaceAuthForSessionAndState(ctx, taskID, sessionID, repo, cloneURL) if err != nil { e.logger.Error("failed to clone repository", zap.String("repository_id", repo.ID), zap.String("repo", repo.ProviderOwner+"/"+repo.ProviderName), zap.Error(err)) - return "", err + return "", state, err } // Persist the local path before reconciliation so a remote-update failure @@ -448,7 +527,7 @@ func (e *Executor) ensureRepoClonedForSession( } } if err := e.reconcileGitHubCheckoutOrigin(ctx, repo, localPath); err != nil { - return "", err + return "", state, err } // Note: default_branch backfill is intentionally driven from @@ -457,7 +536,7 @@ func (e *Executor) ensureRepoClonedForSession( // default_branch was never persisted (e.g. rows created before the // backfill existed). - return localPath, nil + return localPath, state, nil } func (e *Executor) reconcileGitHubCheckoutOrigin( @@ -1047,6 +1126,8 @@ func (e *Executor) buildResumeRequestAtCredentialBoundary( req.PullBeforeWorktree = allRepos[0].PullBeforeWorktree req.RemoteSyncHandled = allRepos[0].RemoteSyncHandled req.RefreshRepository = allRepos[0].RefreshRepository + req.RefreshRepositoryWithState = allRepos[0].RefreshRepositoryWithState + req.RemoteRefState = allRepos[0].RemoteRefState } if err := e.validateReuseEnvironmentInventory(ctx, req, existingEnv); err != nil { return nil, "", execConfig, existingEnv, nil, err diff --git a/apps/backend/internal/repoclone/clone_test.go b/apps/backend/internal/repoclone/clone_test.go index 349958cf90..31d7b4b996 100644 --- a/apps/backend/internal/repoclone/clone_test.go +++ b/apps/backend/internal/repoclone/clone_test.go @@ -7,6 +7,7 @@ import ( "os/exec" "path/filepath" "reflect" + "runtime" "strings" "sync" "testing" @@ -43,6 +44,109 @@ func TestClonerExposesExactScopeWorkspaceClone(t *testing.T) { } } +func TestInspectRemoteRefStateDistinguishesEmptyAndPopulatedRemotes(t *testing.T) { + t.Parallel() + + root := t.TempDir() + emptyRemote := filepath.Join(root, "empty.git") + populatedRemote := filepath.Join(root, "populated.git") + runGit(t, root, "init", "--bare", emptyRemote) + runGit(t, root, "init", "--bare", populatedRemote) + seed := filepath.Join(root, "seed") + runGit(t, root, "clone", populatedRemote, seed) + runGit(t, seed, "config", "user.name", "Test User") + runGit(t, seed, "config", "user.email", "test@example.com") + if err := os.WriteFile(filepath.Join(seed, "README.md"), []byte("seed\n"), 0o644); err != nil { + t.Fatal(err) + } + runGit(t, seed, "add", "README.md") + runGit(t, seed, "commit", "-m", "seed") + runGit(t, seed, "push", "origin", "HEAD:refs/heads/main") + + cloner := NewCloner(Config{BasePath: root}, ProtocolHTTPS, "", logger.Default()) + state, err := cloner.InspectRemoteRefState(context.Background(), emptyRemote, "", "") + if err != nil { + t.Fatalf("empty remote probe error = %v", err) + } + if state != RemoteRefStateEmpty { + t.Fatalf("empty remote state = %q, want %q", state, RemoteRefStateEmpty) + } + state, err = cloner.InspectRemoteRefState(context.Background(), populatedRemote, "", "") + if err != nil { + t.Fatalf("populated remote probe error = %v", err) + } + if state != RemoteRefStateHasRefs { + t.Fatalf("populated remote state = %q, want %q", state, RemoteRefStateHasRefs) + } +} + +func TestInspectLocalRepositoryRemoteRefState(t *testing.T) { + t.Parallel() + + root := t.TempDir() + emptyRemote := filepath.Join(root, "empty.git") + localPath := filepath.Join(root, "checkout") + runGit(t, root, "init", "--bare", emptyRemote) + runGit(t, root, "init", "-b", "main", localPath) + runGit(t, localPath, "remote", "add", "origin", emptyRemote) + + cloner := NewCloner(Config{BasePath: root}, ProtocolHTTPS, "", logger.Default()) + state, err := cloner.InspectLocalRepositoryRemoteRefState(context.Background(), localPath) + if err != nil { + t.Fatalf("empty local remote probe error = %v", err) + } + if state != RemoteRefStateEmpty { + t.Fatalf("empty local remote state = %q, want %q", state, RemoteRefStateEmpty) + } + + if err := os.WriteFile(filepath.Join(localPath, "README.md"), []byte("seed\n"), 0o644); err != nil { + t.Fatal(err) + } + runGit(t, localPath, "add", "README.md") + runGit(t, localPath, "-c", "user.name=Test User", "-c", "user.email=test@example.com", "commit", "-m", "seed") + runGit(t, localPath, "push", "origin", "HEAD:refs/heads/main") + + state, err = cloner.InspectLocalRepositoryRemoteRefState(context.Background(), localPath) + if err != nil { + t.Fatalf("populated local remote probe error = %v", err) + } + if state != RemoteRefStateHasRefs { + t.Fatalf("populated local remote state = %q, want %q", state, RemoteRefStateHasRefs) + } +} + +func TestInspectRemoteRefStateParsesStdoutWhenGitWritesDiagnostics(t *testing.T) { + if runtime.GOOS == "windows" { + t.Skip("shell wrapper test is Unix-only") + } + + scriptDir := t.TempDir() + realGit, err := exec.LookPath("git") + if err != nil { + t.Fatalf("find git: %v", err) + } + shim := "#!/bin/sh\n" + + "if [ \"$1\" = \"ls-remote\" ]; then\n" + + " printf '0123456789012345678901234567890123456789 refs/heads/main\\n'\n" + + " printf 'warning: using a redirected remote\\n' >&2\n" + + " exit 0\n" + + "fi\n" + + "exec \"" + realGit + "\" \"$@\"\n" + if err := os.WriteFile(filepath.Join(scriptDir, "git"), []byte(shim), 0o755); err != nil { + t.Fatalf("write git shim: %v", err) + } + t.Setenv("PATH", scriptDir+string(os.PathListSeparator)+os.Getenv("PATH")) + + cloner := NewCloner(Config{BasePath: t.TempDir()}, ProtocolHTTPS, "", logger.Default()) + state, err := cloner.InspectRemoteRefState(context.Background(), "https://github.com/acme/widgets.git", "", "") + if err != nil { + t.Fatalf("InspectRemoteRefState() error = %v", err) + } + if state != RemoteRefStateHasRefs { + t.Fatalf("remote state = %q, want %q", state, RemoteRefStateHasRefs) + } +} + func TestClonerBuildCloneURLUsesCurrentProtocol(t *testing.T) { resolver := &mutableGitProtocolResolver{protocol: ProtocolHTTPS} cloner := NewClonerWithProtocolResolver( diff --git a/apps/backend/internal/repoclone/remote_state.go b/apps/backend/internal/repoclone/remote_state.go new file mode 100644 index 0000000000..f5207c9b98 --- /dev/null +++ b/apps/backend/internal/repoclone/remote_state.go @@ -0,0 +1,201 @@ +package repoclone + +import ( + "bytes" + "context" + "fmt" + "strings" + + "github.com/kandev/kandev/internal/common/subproc" +) + +// RemoteRefState describes what an authenticated remote advertised after a +// clone or strict refresh. +type RemoteRefState string + +const ( + RemoteRefStateUnknown RemoteRefState = "unknown" + RemoteRefStateHasRefs RemoteRefState = "has_refs" + RemoteRefStateEmpty RemoteRefState = "empty" +) + +// InspectRemoteRefState probes a remote with the supplied credential scope. +// An empty successful advertisement is distinct from an unavailable or +// malformed advertisement, which remains unknown and fails closed upstream. +func (c *Cloner) InspectRemoteRefState( + ctx context.Context, cloneURL, credentialOrigin, token string, +) (RemoteRefState, error) { + auth, err := credentialAuth(cloneURL, credentialOrigin, token) + if err != nil { + return RemoteRefStateUnknown, err + } + return c.remoteRefState(ctx, cloneURL, auth) +} + +// InspectLocalRepositoryRemoteRefState probes the origin configured in a +// user-owned checkout without resolving or exposing the configured URL. This +// keeps local repositories on the same typed state path as managed clones +// while preserving local Git credential-helper behavior. +func (c *Cloner) InspectLocalRepositoryRemoteRefState( + ctx context.Context, repositoryPath string, +) (RemoteRefState, error) { + if strings.TrimSpace(repositoryPath) == "" { + return RemoteRefStateUnknown, fmt.Errorf("repository path is required") + } + cmd := subproc.NewGitCommand(ctx, "-C", repositoryPath, "ls-remote", "--refs", "origin") + cleanup, err := configureGitCommand(cmd, nil) + if err != nil { + return RemoteRefStateUnknown, err + } + defer cleanup() + var stderr bytes.Buffer + cmd.Stderr = &stderr + output, err := subproc.RunGitOutputClass(ctx, subproc.GitLifecycle, cmd) + if err != nil { + diagnostic := redactCloneOutput(stderr.String(), "") + return RemoteRefStateUnknown, fmt.Errorf("inspect local repository refs: %s: %w", + strings.TrimSpace(diagnostic), err) + } + return parseRemoteRefState(string(output)) +} + +func (c *Cloner) remoteRefState(ctx context.Context, cloneURL string, auth *cloneAuth) (RemoteRefState, error) { + cmd := subproc.NewGitCommand(ctx, "ls-remote", "--refs", "--", cloneURL) + cleanup, err := configureGitCommand(cmd, auth) + if err != nil { + return RemoteRefStateUnknown, err + } + defer cleanup() + var stderr bytes.Buffer + cmd.Stderr = &stderr + output, err := subproc.RunGitOutputClass(ctx, subproc.GitLifecycle, cmd) + if err != nil { + diagnostic := redactCloneOutput(stderr.String(), authToken(auth)) + return RemoteRefStateUnknown, fmt.Errorf("inspect remote refs: %s: %w", + strings.TrimSpace(diagnostic), err) + } + return parseRemoteRefState(string(output)) +} + +func parseRemoteRefState(output string) (RemoteRefState, error) { + hasRef := false + for _, line := range strings.Split(strings.TrimSpace(output), "\n") { + line = strings.TrimSpace(line) + if line == "" { + continue + } + fields := strings.Fields(line) + if len(fields) != 2 || !strings.HasPrefix(fields[1], "refs/") { + return RemoteRefStateUnknown, fmt.Errorf("malformed remote ref advertisement") + } + hasRef = true + } + if !hasRef { + return RemoteRefStateEmpty, nil + } + return RemoteRefStateHasRefs, nil +} + +// EnsureWorkspaceClonedWithCredentialRequestAndState performs the existing +// workspace clone flow and returns the authenticated remote-ref state. +func (c *Cloner) EnsureWorkspaceClonedWithCredentialRequestAndState( + ctx context.Context, request GitCredentialRequest, credentialOrigin, token string, +) (string, RemoteRefState, error) { + targetPath, err := c.WorkspaceProviderRepositoryPath( + request.WorkspaceID, request.Provider, request.ProviderHost, request.ProviderScope, + request.ProviderRepositoryID, request.Owner, request.Name, + ) + if err != nil { + return "", RemoteRefStateUnknown, err + } + cloneURL, auth, err := c.workspaceCloneAuthRequest(ctx, request, credentialOrigin, token) + if err != nil { + return "", RemoteRefStateUnknown, err + } + if _, err := c.ensureClonedAtPathWithOriginVerification( + ctx, cloneURL, targetPath, auth, request.ProviderScope != "" && request.ProviderRepositoryID != "", + ); err != nil { + return targetPath, RemoteRefStateUnknown, err + } + state, err := c.remoteRefState(ctx, cloneURL, auth) + if err != nil { + return targetPath, RemoteRefStateUnknown, err + } + return targetPath, state, nil +} + +// EnsureWorkspaceClonedWithBasicAuthAndState is the typed-state variant of +// EnsureWorkspaceClonedWithBasicAuth for providers using PAT/basic auth. +func (c *Cloner) EnsureWorkspaceClonedWithBasicAuthAndState( + ctx context.Context, workspaceID, provider, providerHost, + cloneURL, owner, name, username, password string, +) (string, RemoteRefState, error) { + targetPath, err := c.WorkspaceProviderRepoPath(workspaceID, provider, providerHost, owner, name) + if err != nil { + return "", RemoteRefStateUnknown, err + } + if _, err := c.ensureClonedWithBasicAuth(ctx, targetPath, cloneURL, username, password); err != nil { + return targetPath, RemoteRefStateUnknown, err + } + origin, err := gitCredentialOrigin(cloneURL) + if err != nil { + return targetPath, RemoteRefStateUnknown, err + } + state, err := c.remoteRefState(ctx, cloneURL, &cloneAuth{ + origin: origin, username: username, password: password, + }) + if err != nil { + return targetPath, RemoteRefStateUnknown, err + } + return targetPath, state, nil +} + +// RefreshWorkspaceRepositoryWithCredentialRequestAndState strictly refreshes +// a workspace checkout and returns the authenticated remote-ref state. +func (c *Cloner) RefreshWorkspaceRepositoryWithCredentialRequestAndState( + ctx context.Context, request GitCredentialRequest, repositoryPath, credentialOrigin, token string, +) (RemoteRefState, error) { + targetPath, err := c.WorkspaceProviderRepositoryPath( + request.WorkspaceID, request.Provider, request.ProviderHost, request.ProviderScope, + request.ProviderRepositoryID, request.Owner, request.Name, + ) + if err != nil { + return RemoteRefStateUnknown, err + } + if !sameFilesystemPath(targetPath, repositoryPath) { + return RemoteRefStateUnknown, fmt.Errorf("repository path does not match the scoped workspace checkout") + } + cloneURL, auth, err := c.workspaceCloneAuthRequest(ctx, request, credentialOrigin, token) + if err != nil { + return RemoteRefStateUnknown, err + } + if err := c.refreshWorkspaceRepository(ctx, targetPath, cloneURL, auth, request.PRNumber); err != nil { + return RemoteRefStateUnknown, err + } + return c.remoteRefState(ctx, cloneURL, auth) +} + +// RefreshWorkspaceRepositoryWithBasicAuthAndState is the typed-state variant +// of RefreshWorkspaceRepositoryWithBasicAuth for providers using PAT/basic +// authentication. +func (c *Cloner) RefreshWorkspaceRepositoryWithBasicAuthAndState( + ctx context.Context, workspaceID, provider, providerHost, + cloneURL, owner, name, repositoryPath, username, password string, +) (RemoteRefState, error) { + targetPath, err := c.WorkspaceProviderRepoPath(workspaceID, provider, providerHost, owner, name) + if err != nil { + return RemoteRefStateUnknown, err + } + if !sameFilesystemPath(targetPath, repositoryPath) { + return RemoteRefStateUnknown, fmt.Errorf("repository path does not match the workspace checkout") + } + origin, err := gitCredentialOrigin(cloneURL) + if err != nil { + return RemoteRefStateUnknown, err + } + auth := &cloneAuth{origin: origin, username: username, password: password} + if err := c.refreshWorkspaceRepository(ctx, targetPath, cloneURL, auth, 0); err != nil { + return RemoteRefStateUnknown, err + } + return c.remoteRefState(ctx, cloneURL, auth) +} diff --git a/apps/backend/internal/worktree/manager_empty_remote_test.go b/apps/backend/internal/worktree/manager_empty_remote_test.go new file mode 100644 index 0000000000..664be3d655 --- /dev/null +++ b/apps/backend/internal/worktree/manager_empty_remote_test.go @@ -0,0 +1,160 @@ +package worktree + +import ( + "context" + "os" + "path/filepath" + "strings" + "testing" + + "github.com/kandev/kandev/internal/gitbootstrap" + "github.com/kandev/kandev/internal/repoclone" +) + +func TestCreateSeedsEmptyRemoteBaselineBeforeAddingWorktree(t *testing.T) { + cfg := newTestConfig(t) + mgr, err := NewManager(cfg, newMockStore(), newTestLogger()) + if err != nil { + t.Fatalf("NewManager() error = %v", err) + } + repoPath := t.TempDir() + runGit(t, repoPath, "init", "-b", "main") + + wt, err := mgr.Create(context.Background(), CreateRequest{ + TaskID: "task-empty", + SessionID: "session-empty", + RepositoryID: "repo-empty", + RepositoryPath: repoPath, + BaseBranch: "main", + TaskDirName: "task-empty", + RepoName: "repo-empty", + RemoteSyncHandled: true, + RemoteRefState: repoclone.RemoteRefStateEmpty, + }) + if err != nil { + t.Fatalf("Create() error = %v", err) + } + if wt.BaseBranch != "main" { + t.Fatalf("worktree BaseBranch = %q, want main", wt.BaseBranch) + } + if got := strings.TrimSpace(runGit(t, repoPath, "rev-parse", "refs/heads/main")); got == "" { + t.Fatal("empty-remote baseline did not create refs/heads/main") + } + baseline, present, err := gitbootstrap.Validate(context.Background(), repoPath, "main") + if err != nil { + t.Fatalf("Validate() error = %v", err) + } + if !present || baseline.Commit == "" { + t.Fatalf("Validate() = (%+v, %v), want a present baseline", baseline, present) + } + if got := strings.TrimSpace(runGit(t, wt.Path, "rev-parse", "HEAD")); got != baseline.Commit { + t.Fatalf("worktree HEAD = %q, want baseline %q", got, baseline.Commit) + } +} + +func TestCreateReevaluatesAnEmptyRemoteRaceAgainstExistingLocalBase(t *testing.T) { + cfg := newTestConfig(t) + mgr, err := NewManager(cfg, newMockStore(), newTestLogger()) + if err != nil { + t.Fatalf("NewManager() error = %v", err) + } + repoPath := t.TempDir() + runGit(t, repoPath, "init", "-b", "main") + if err := os.WriteFile(filepath.Join(repoPath, "README.md"), []byte("existing\n"), 0o644); err != nil { + t.Fatal(err) + } + runGit(t, repoPath, "add", "README.md") + runGit(t, repoPath, "-c", "user.name=Test User", "-c", "user.email=test@example.com", "commit", "-m", "existing") + + wt, err := mgr.Create(context.Background(), CreateRequest{ + TaskID: "task-empty-race", + SessionID: "session-empty-race", + RepositoryID: "repo-empty-race", + RepositoryPath: repoPath, + BaseBranch: "main", + TaskDirName: "task-empty-race", + RepoName: "repo-empty-race", + RemoteRefState: repoclone.RemoteRefStateEmpty, + }) + if err != nil { + t.Fatalf("Create() error = %v", err) + } + if got := strings.TrimSpace(runGit(t, wt.Path, "rev-parse", "HEAD")); got == "" { + t.Fatal("worktree did not retain the existing local base after the empty-remote race") + } + if _, present, err := gitbootstrap.Validate(context.Background(), repoPath, "main"); err != nil { + t.Fatalf("Validate() error = %v", err) + } else if present { + t.Fatal("empty-remote race unexpectedly created a bootstrap marker for an existing local base") + } +} + +func TestCreateReevaluatesAnEmptyRemoteRaceWithRemoteSyncHandled(t *testing.T) { + cfg := newTestConfig(t) + mgr, err := NewManager(cfg, newMockStore(), newTestLogger()) + if err != nil { + t.Fatalf("NewManager() error = %v", err) + } + repoPath := t.TempDir() + runGit(t, repoPath, "init", "-b", "main") + if err := os.WriteFile(filepath.Join(repoPath, "README.md"), []byte("existing\n"), 0o644); err != nil { + t.Fatal(err) + } + runGit(t, repoPath, "add", "README.md") + runGit(t, repoPath, "-c", "user.name=Test User", "-c", "user.email=test@example.com", "commit", "-m", "existing") + + wt, err := mgr.Create(context.Background(), CreateRequest{ + TaskID: "task-empty-race-refreshed", + SessionID: "session-empty-race-refreshed", + RepositoryID: "repo-empty-race-refreshed", + RepositoryPath: repoPath, + BaseBranch: "main", + TaskDirName: "task-empty-race-refreshed", + RepoName: "repo-empty-race-refreshed", + RemoteSyncHandled: true, + RemoteRefState: repoclone.RemoteRefStateEmpty, + }) + if err != nil { + t.Fatalf("Create() error = %v", err) + } + if got := strings.TrimSpace(runGit(t, wt.Path, "rev-parse", "HEAD")); got == "" { + t.Fatal("worktree did not retain the existing local base after the refreshed empty-remote race") + } +} + +func TestCreateRecreatesEmptyRemoteWorktreeFromLocalBaseline(t *testing.T) { + cfg := newTestConfig(t) + mgr, err := NewManager(cfg, newMockStore(), newTestLogger()) + if err != nil { + t.Fatalf("NewManager() error = %v", err) + } + repoPath := t.TempDir() + runGit(t, repoPath, "init", "-b", "main") + + req := CreateRequest{ + TaskID: "task-empty-recreate", + SessionID: "session-empty-recreate", + RepositoryID: "repo-empty-recreate", + RepositoryPath: repoPath, + BaseBranch: "main", + TaskDirName: "task-empty-recreate", + RepoName: "repo-empty-recreate", + RemoteSyncHandled: true, + RemoteRefState: repoclone.RemoteRefStateEmpty, + } + first, err := mgr.Create(context.Background(), req) + if err != nil { + t.Fatalf("initial Create() error = %v", err) + } + if err := os.RemoveAll(first.Path); err != nil { + t.Fatalf("remove worktree: %v", err) + } + + recreated, err := mgr.Create(context.Background(), req) + if err != nil { + t.Fatalf("recreate Create() error = %v", err) + } + if got := strings.TrimSpace(runGit(t, recreated.Path, "rev-parse", "HEAD")); got == "" { + t.Fatal("recreated empty-remote worktree has no local commit") + } +} diff --git a/apps/backend/internal/worktree/manager_lifecycle.go b/apps/backend/internal/worktree/manager_lifecycle.go index 0c1de8cab4..a5046cda8f 100644 --- a/apps/backend/internal/worktree/manager_lifecycle.go +++ b/apps/backend/internal/worktree/manager_lifecycle.go @@ -15,6 +15,8 @@ import ( storageworkspaces "github.com/kandev/kandev/internal/system/storage/workspaces" "go.uber.org/zap" + "github.com/kandev/kandev/internal/gitbootstrap" + "github.com/kandev/kandev/internal/repoclone" "github.com/kandev/kandev/internal/worktree/copyfiles" ) @@ -168,7 +170,20 @@ func (m *Manager) Create(ctx context.Context, req CreateRequest) (*Worktree, err // checked by the caller first, so a valid existing worktree never refreshes // origin or incurs provider authentication work. func (m *Manager) refreshRepositoryForMaterialization(ctx context.Context, req *CreateRequest) error { - if req == nil || req.RemoteSyncHandled || req.RefreshRepository == nil { + if req == nil || req.RemoteSyncHandled { + return nil + } + if req.RefreshRepositoryWithState != nil { + state, err := req.RefreshRepositoryWithState(ctx) + if err != nil { + return err + } + req.RemoteRefState = state + req.RemoteSyncHandled = true + req.PullBeforeWorktree = false + return nil + } + if req.RefreshRepository == nil { return nil } if err := req.RefreshRepository(ctx); err != nil { @@ -179,6 +194,25 @@ func (m *Manager) refreshRepositoryForMaterialization(ctx context.Context, req * return nil } +func (m *Manager) ensureEmptyRemoteBaseline(ctx context.Context, req *CreateRequest) (string, error) { + if req == nil || req.RemoteRefState != repoclone.RemoteRefStateEmpty { + return "", nil + } + baseline, err := gitbootstrap.Ensure(ctx, req.RepositoryPath, req.BaseBranch) + if errors.Is(err, gitbootstrap.ErrBaselineConflict) { + req.RemoteRefState = repoclone.RemoteRefStateHasRefs + req.RemoteSyncHandled = false + baseBranch := strings.TrimPrefix(strings.TrimSpace(req.BaseBranch), "origin/") + return strings.TrimPrefix(baseBranch, "refs/heads/"), nil + } + if err != nil { + return "", fmt.Errorf("seed empty-remote local baseline: %w", err) + } + req.RemoteSyncHandled = true + req.PullBeforeWorktree = false + return baseline.BaseRef, nil +} + // reuseRequiredWorktree resolves the exact canonical worktree for an // additional session. It intentionally performs no Git operation and does // not run contribution setup or repository scripts: another active session @@ -470,9 +504,23 @@ func requestBranchIdentitySlug(req CreateRequest) string { // returned for surfacing on the resulting worktree record. func (m *Manager) resolveBaseRefWithFallback(ctx context.Context, req *CreateRequest) (baseRef, warning, detail string, err error) { baseRef = req.BaseBranch - if req.RemoteSyncHandled { + switch { + case req.RemoteRefState == repoclone.RemoteRefStateEmpty: + baselineRef, baselineErr := m.ensureEmptyRemoteBaseline(ctx, req) + if baselineErr != nil { + return "", "", "", baselineErr + } + switch { + case baselineRef != "": + baseRef = baselineRef + case req.RemoteSyncHandled: + baseRef, err = m.preferRefreshedRemoteRef(ctx, req.RepositoryPath, req.BaseBranch) + case req.PullBeforeWorktree: + baseRef, err = m.pullBaseBranch(ctx, req.RepositoryPath, req.BaseBranch, req.OnSyncProgress) + } + case req.RemoteSyncHandled: baseRef, err = m.preferRefreshedRemoteRef(ctx, req.RepositoryPath, req.BaseBranch) - } else if req.PullBeforeWorktree { + case req.PullBeforeWorktree: baseRef, err = m.pullBaseBranch(ctx, req.RepositoryPath, req.BaseBranch, req.OnSyncProgress) } if err != nil { @@ -1681,6 +1729,10 @@ func (m *Manager) recreate(ctx context.Context, existing *Worktree, req CreateRe repoLock.Unlock() m.releaseRepoLock(req.RepositoryPath) }() + emptyRemoteBaseRef, err := m.ensureEmptyRemoteBaseline(ctx, &req) + if err != nil { + return nil, err + } // Reuse the original on-disk path so the worktree is recreated in the // same task-dir slot it was first created in. @@ -1714,7 +1766,7 @@ func (m *Manager) recreate(ctx context.Context, existing *Worktree, req CreateRe } } refreshedStartPoint := "" - if req.RemoteSyncHandled && req.RemoteContribution == nil { + if req.RemoteSyncHandled && req.RemoteContribution == nil && emptyRemoteBaseRef == "" { sourceBranch := existing.Branch if req.CheckoutBranch != "" { sourceBranch = req.CheckoutBranch @@ -1739,6 +1791,11 @@ func (m *Manager) recreate(ctx context.Context, existing *Worktree, req CreateRe if output, branchErr := runGitCmdCombinedOutput(ctx, branchCmd); branchErr != nil { return nil, fmt.Errorf("restore contribution branch: %s: %w", strings.TrimSpace(string(output)), branchErr) } + } else if emptyRemoteBaseRef != "" { + branchCmd := m.newNonInteractiveGitCmd(ctx, req.RepositoryPath, "branch", existing.Branch, emptyRemoteBaseRef) + if output, branchErr := runGitCmdCombinedOutput(ctx, branchCmd); branchErr != nil { + return nil, fmt.Errorf("restore empty-remote worktree branch: %s: %w", strings.TrimSpace(string(output)), branchErr) + } } else { if _, fetchErr := m.fetchBranchToLocalWithPolicy( ctx, req.RepositoryPath, existing.Branch, req.PRNumber, diff --git a/apps/backend/internal/worktree/worktree.go b/apps/backend/internal/worktree/worktree.go index 1b7acd160d..6da79ce858 100644 --- a/apps/backend/internal/worktree/worktree.go +++ b/apps/backend/internal/worktree/worktree.go @@ -5,6 +5,7 @@ import ( "fmt" "time" + "github.com/kandev/kandev/internal/repoclone" "github.com/kandev/kandev/internal/task/models" ) @@ -217,6 +218,15 @@ type CreateRequest struct { // handled before selecting local refs. RefreshRepository func(context.Context) error + // RefreshRepositoryWithState is the typed variant used by managed clones. + // Only RemoteRefStateEmpty permits local empty-remote bootstrap; unknown + // state remains fail-closed and follows the ordinary refresh rules. + RefreshRepositoryWithState func(context.Context) (repoclone.RemoteRefState, error) + + // RemoteRefState is the result of the authenticated remote advertisement + // used for this materialization. + RemoteRefState repoclone.RemoteRefState + // WorktreeID is the ID of an existing worktree to reuse (optional). // If provided and valid, the existing worktree is returned instead of creating a new one. WorktreeID string diff --git a/apps/web/components/task/changes-panel-hooks.test.ts b/apps/web/components/task/changes-panel-hooks.test.ts index 1eb7bcf518..c2396cb132 100644 --- a/apps/web/components/task/changes-panel-hooks.test.ts +++ b/apps/web/components/task/changes-panel-hooks.test.ts @@ -18,8 +18,13 @@ afterEach(async () => { await i18n.changeLanguage("en"); }); -const repo = (name: string, success: boolean, error?: string): PerRepoOperationResult => - ({ repository_name: name, success, error }) as PerRepoOperationResult; +const repo = ( + name: string, + success: boolean, + error?: string, + errorCode?: string, +): PerRepoOperationResult => + ({ repository_name: name, success, error, error_code: errorCode }) as PerRepoOperationResult; const noPlaceholders = (result: { title: string; description: string }) => { expect(result.title).not.toContain("{{"); @@ -76,6 +81,18 @@ describe("describePerRepo", () => { expect(two.description).toContain("2 repos:"); }); + it("uses localized recovery copy for a bounded publication failure", () => { + const result = describePerRepo( + [repo("api", false, "raw remote output", "empty_remote_remote_changed")], + "Push", + ); + + expect(result.description).toBe( + "Failed in 1 repo: api: The remote changed before the base branch was published. Refresh the task and try again.", + ); + expect(result.description).not.toContain("raw remote output"); + }); + it("keeps every branch resolving after a locale switch", async () => { await i18n.changeLanguage("pseudo"); diff --git a/apps/web/components/task/changes-panel-hooks.ts b/apps/web/components/task/changes-panel-hooks.ts index 0be540ad55..bfd7c71154 100644 --- a/apps/web/components/task/changes-panel-hooks.ts +++ b/apps/web/components/task/changes-panel-hooks.ts @@ -3,6 +3,7 @@ import { useRef, useState, useCallback } from "react"; import { t } from "@/lib/i18n"; import { gitOperationLabel } from "@/hooks/use-git-with-feedback"; +import { getLocalizedGitOperationError } from "@/hooks/use-git-operations"; import type { useToast } from "@/components/toast-provider"; import type { SessionGit, PerRepoOperationResult } from "@/hooks/domains/session/use-session-git"; @@ -30,6 +31,7 @@ type GitOperationResultLike = { success: boolean; output: string; error?: string; + error_code?: string; per_repo?: PerRepoOperationResult[]; }; type GitOperationFn = (op: () => Promise, name: string) => Promise; @@ -50,7 +52,7 @@ export function describePerRepo( .map((r) => t("common:gitOperationRepoFailure", { repo: r.repository_name, - error: r.error || t("common:unknownError"), + error: getLocalizedGitOperationError(r.error_code, r.error) || t("common:unknownError"), }), ) .join("; "); @@ -116,7 +118,8 @@ export function useChangesGitHandlers( const description = result.success ? result.output.slice(0, 200) || t("common:gitOperationCompleted", { operation: operationName }) - : result.error || t("common:anErrorOccurred"); + : getLocalizedGitOperationError(result.error_code, result.error) || + t("common:anErrorOccurred"); toast({ title, description, variant }); } catch (e) { toast({ diff --git a/apps/web/components/vcs/change-request-feedback.test.ts b/apps/web/components/vcs/change-request-feedback.test.ts index bde9349e4b..9378caa3c7 100644 --- a/apps/web/components/vcs/change-request-feedback.test.ts +++ b/apps/web/components/vcs/change-request-feedback.test.ts @@ -65,4 +65,22 @@ describe("getChangeRequestFailureFeedback", () => { variant: "error", }); }); + + it("maps empty-remote publication failures to recovery copy", () => { + expect( + getChangeRequestFailureFeedback( + { + success: false, + provider: "github", + error: "raw push output", + error_code: "empty_remote_branch_publish_failed", + }, + getChangeRequestTerminology("github"), + ), + ).toEqual({ + title: "Create PR failed", + description: "The base branch was published, but the task branch was not. Try Push again.", + variant: "error", + }); + }); }); diff --git a/apps/web/components/vcs/change-request-feedback.ts b/apps/web/components/vcs/change-request-feedback.ts index 3898fb9055..fc2b5827b0 100644 --- a/apps/web/components/vcs/change-request-feedback.ts +++ b/apps/web/components/vcs/change-request-feedback.ts @@ -1,4 +1,5 @@ import { + getLocalizedGitOperationError, resolveChangeRequestTerminology, type PRCreateResult, type getChangeRequestTerminology, @@ -37,6 +38,7 @@ export function getChangeRequestSuccessFeedback( export function getChangeRequestFailureFeedback(result: PRCreateResult, fallback: Terminology) { const terms = resolveChangeRequestTerminology(result.provider, fallback); + const localizedError = getLocalizedGitOperationError(result.error_code, result.error); if (result.branch_pushed) { return { title: t("integrations:branchPushedNotCreated", { shortName: terms.shortName }), @@ -48,7 +50,7 @@ export function getChangeRequestFailureFeedback(result: PRCreateResult, fallback } return { title: t("integrations:createFailed", { shortName: terms.shortName }), - description: result.error || t("integrations:anErrorOccurred"), + description: localizedError || t("integrations:anErrorOccurred"), variant: "error" as const, }; } diff --git a/apps/web/e2e/fixtures/test-base.ts b/apps/web/e2e/fixtures/test-base.ts index 7d9fe3043c..a4de652354 100644 --- a/apps/web/e2e/fixtures/test-base.ts +++ b/apps/web/e2e/fixtures/test-base.ts @@ -515,7 +515,7 @@ export function resetSeedRepositoryCheckout(seedData: SeedData, tmpDir: string) }); } -/** Points the seed repository at an empty remote whose HEAD cannot resolve. */ +/** Points the seed repository at a non-empty remote whose HEAD cannot resolve. */ export function pointSeedRepositoryAtUnresolvedOrigin(seedData: SeedData, tmpDir: string) { const remoteDir = path.join( tmpDir, @@ -527,6 +527,11 @@ export function pointSeedRepositoryAtUnresolvedOrigin(seedData: SeedData, tmpDir env: makeGitEnv(tmpDir), stdio: "ignore", }); + execFileSync( + "git", + ["-C", seedData.repositoryPath, "push", "--no-verify", remoteDir, "main:refs/heads/unrelated"], + { env: makeGitEnv(tmpDir), stdio: "ignore" }, + ); try { execFileSync( "git", diff --git a/apps/web/e2e/helpers/empty-remote-repository.ts b/apps/web/e2e/helpers/empty-remote-repository.ts new file mode 100644 index 0000000000..c33f739725 --- /dev/null +++ b/apps/web/e2e/helpers/empty-remote-repository.ts @@ -0,0 +1,102 @@ +import { expect, type Page } from "@playwright/test"; +import { execFileSync } from "node:child_process"; +import fs from "node:fs"; +import path from "node:path"; +import { pathToFileURL } from "node:url"; +import type { ApiClient } from "./api-client"; +import { GitHelper, makeGitEnv } from "./git-helper"; +import { SessionPage } from "../pages/session-page"; + +export type EmptyRemoteRepository = { + localPath: string; + remotePath: string; + remoteURL: string; + gitEnv: NodeJS.ProcessEnv; + cleanup: () => void; +}; + +export function createEmptyRemoteRepository(tmpDir: string, label: string): EmptyRemoteRepository { + const root = path.join(tmpDir, "repos", `empty-remote-${label}-${Date.now()}-${process.pid}`); + const remotePath = path.join(root, "origin.git"); + const localPath = path.join(root, "checkout"); + const gitEnv = makeGitEnv(tmpDir); + + fs.mkdirSync(path.dirname(root), { recursive: true }); + execFileSync("git", ["init", "--bare", "-b", "main", remotePath], { + env: gitEnv, + stdio: "ignore", + }); + execFileSync("git", ["init", "-b", "main", localPath], { + env: gitEnv, + stdio: "ignore", + }); + const remoteURL = pathToFileURL(remotePath).href; + execFileSync("git", ["remote", "add", "origin", remoteURL], { + cwd: localPath, + env: gitEnv, + stdio: "ignore", + }); + + return { + localPath, + remotePath, + remoteURL, + gitEnv, + cleanup: () => fs.rmSync(root, { recursive: true, force: true }), + }; +} + +export async function openTaskByID(page: Page, taskID: string): Promise { + await page.goto(`/t/${taskID}`); + const session = new SessionPage(page); + await session.waitForLoad(); + return session; +} + +export async function waitForTaskWorktree( + apiClient: ApiClient, + taskID: string, + repositoryID: string, +): Promise { + await expect + .poll( + async () => { + const environment = await apiClient.getTaskEnvironment(taskID); + const repositoryWorktree = environment?.repos?.find( + (repo) => repo.repository_id === repositoryID, + )?.worktree_path; + return ( + repositoryWorktree || environment?.worktree_path || environment?.workspace_path || "" + ); + }, + { timeout: 60_000, message: "Waiting for the empty-remote task worktree" }, + ) + .not.toBe(""); + + const environment = await apiClient.getTaskEnvironment(taskID); + const repositoryWorktree = environment?.repos?.find( + (repo) => repo.repository_id === repositoryID, + )?.worktree_path; + const worktreePath = + repositoryWorktree || environment?.worktree_path || environment?.workspace_path; + if (!worktreePath) throw new Error("Empty-remote task environment has no worktree path"); + return worktreePath; +} + +export function remoteRef(git: GitHelper, branch: string): string { + const output = git.exec(`git ls-remote --refs origin refs/heads/${branch}`).trim(); + return output.split(/\s+/u)[0] || ""; +} + +export async function removeTestRepository(apiClient: ApiClient, repositoryID: string) { + const response = await apiClient.rawRequest("DELETE", `/api/v1/repositories/${repositoryID}`); + if (!response.ok && response.status !== 404 && response.status !== 409) { + throw new Error( + `Failed to remove empty-remote test repository (${response.status}): ${await response.text()}`, + ); + } +} + +export function taskWorktreeGit(pathname: string, gitEnv: NodeJS.ProcessEnv): GitHelper { + return new GitHelper(pathname, gitEnv); +} diff --git a/apps/web/e2e/tests/git/empty-remote-repository.spec.ts b/apps/web/e2e/tests/git/empty-remote-repository.spec.ts new file mode 100644 index 0000000000..f1ec6b63b6 --- /dev/null +++ b/apps/web/e2e/tests/git/empty-remote-repository.spec.ts @@ -0,0 +1,76 @@ +import { test, expect } from "../../fixtures/test-base"; +import { + createEmptyRemoteRepository, + openTaskByID, + remoteRef, + removeTestRepository, + taskWorktreeGit, + waitForTaskWorktree, +} from "../../helpers/empty-remote-repository"; + +test.describe("Empty remote repository", () => { + test.setTimeout(180_000); + + test("launches without remote mutation and publishes base before the task branch", async ({ + testPage, + apiClient, + seedData, + backend, + }) => { + const fixture = createEmptyRemoteRepository(backend.tmpDir, "desktop"); + let repositoryID = ""; + try { + const repository = await apiClient.createRepository( + seedData.workspaceId, + fixture.localPath, + "main", + { name: "Empty Remote Desktop" }, + ); + repositoryID = repository.id; + const task = await apiClient.createTaskWithAgent( + seedData.workspaceId, + "Empty remote desktop publication", + seedData.agentProfileId, + { + description: "/e2e:simple-message", + workflow_id: seedData.workflowId, + workflow_step_id: seedData.startStepId, + executor_profile_id: seedData.worktreeExecutorProfileId, + repositories: [{ repository_id: repositoryID, base_branch: "main" }], + }, + ); + + const session = await openTaskByID(testPage, task.id); + await session.waitForChatIdle({ timeout: 60_000 }); + const worktreePath = await waitForTaskWorktree(apiClient, task.id, repositoryID); + const git = taskWorktreeGit(worktreePath, fixture.gitEnv); + + expect(git.exec("git ls-remote --refs origin").trim()).toBe(""); + const baseCommit = git.exec("git rev-parse refs/heads/main").trim(); + expect(git.exec("git rev-list --count refs/heads/main").trim()).toBe("1"); + expect(git.exec("git ls-tree --name-only refs/heads/main").trim()).toBe(""); + + git.createFile("empty-remote-desktop.txt", "published through Changes\n"); + git.stageAll(); + const taskCommit = git.commit("Add empty remote desktop fixture"); + const taskBranch = git.exec("git branch --show-current").trim(); + + await session.clickTab("Changes"); + await expect(session.changes).toBeVisible({ timeout: 15_000 }); + await session.expandCommitsSection(); + const pushButton = session.changes.getByTestId("commits-repo-push"); + await expect(pushButton).toBeVisible({ timeout: 15_000 }); + await pushButton.click(); + + await expect( + testPage.getByTestId("toast-message").filter({ hasText: "Push successful" }), + ).toBeVisible({ timeout: 30_000 }); + await expect.poll(() => remoteRef(git, "main"), { timeout: 30_000 }).toBe(baseCommit); + await expect.poll(() => remoteRef(git, taskBranch), { timeout: 30_000 }).toBe(taskCommit); + } finally { + await apiClient.e2eReset(seedData.workspaceId, [seedData.workflowId]).catch(() => undefined); + if (repositoryID) await removeTestRepository(apiClient, repositoryID); + fixture.cleanup(); + } + }); +}); diff --git a/apps/web/e2e/tests/git/mobile-empty-remote-repository.spec.ts b/apps/web/e2e/tests/git/mobile-empty-remote-repository.spec.ts new file mode 100644 index 0000000000..85754b4d66 --- /dev/null +++ b/apps/web/e2e/tests/git/mobile-empty-remote-repository.spec.ts @@ -0,0 +1,86 @@ +import { test, expect } from "../../fixtures/test-base"; +import { + createEmptyRemoteRepository, + openTaskByID, + remoteRef, + removeTestRepository, + taskWorktreeGit, + waitForTaskWorktree, +} from "../../helpers/empty-remote-repository"; + +test.describe("Mobile empty remote repository", () => { + test.setTimeout(180_000); + + test("publishes base and task branches through the touch Changes path", async ({ + testPage, + apiClient, + seedData, + backend, + }) => { + const fixture = createEmptyRemoteRepository(backend.tmpDir, "mobile"); + let repositoryID = ""; + try { + const repository = await apiClient.createRepository( + seedData.workspaceId, + fixture.localPath, + "main", + { name: "Empty Remote Mobile" }, + ); + repositoryID = repository.id; + const task = await apiClient.createTaskWithAgent( + seedData.workspaceId, + "Empty remote mobile publication", + seedData.agentProfileId, + { + description: "/e2e:simple-message", + workflow_id: seedData.workflowId, + workflow_step_id: seedData.startStepId, + executor_profile_id: seedData.worktreeExecutorProfileId, + repositories: [{ repository_id: repositoryID, base_branch: "main" }], + }, + ); + + const session = await openTaskByID(testPage, task.id); + await session.waitForChatIdle({ timeout: 60_000 }); + const worktreePath = await waitForTaskWorktree(apiClient, task.id, repositoryID); + const git = taskWorktreeGit(worktreePath, fixture.gitEnv); + + expect(git.exec("git ls-remote --refs origin").trim()).toBe(""); + const baseCommit = git.exec("git rev-parse refs/heads/main").trim(); + git.createFile("empty-remote-mobile.txt", "published through mobile Changes\n"); + git.stageAll(); + const taskCommit = git.commit("Add empty remote mobile fixture"); + const taskBranch = git.exec("git branch --show-current").trim(); + + await testPage.getByRole("button", { name: "Changes" }).tap(); + const changesPanel = testPage.getByTestId("mobile-changes-panel"); + await expect(changesPanel).toBeVisible({ timeout: 15_000 }); + const commitsToggle = changesPanel.getByTestId("commits-section-collapse-toggle"); + await expect(commitsToggle).toBeVisible({ timeout: 15_000 }); + await expect + .poll( + async () => { + if ((await commitsToggle.getAttribute("aria-expanded")) === "true") return true; + await commitsToggle.tap(); + return (await commitsToggle.getAttribute("aria-expanded")) === "true"; + }, + { timeout: 15_000 }, + ) + .toBe(true); + + const pushButton = changesPanel.getByTestId("commits-repo-push"); + await expect(pushButton).toBeVisible({ timeout: 15_000 }); + await pushButton.tap(); + + await expect( + testPage.getByTestId("toast-message").filter({ hasText: "Push successful" }), + ).toBeVisible({ timeout: 30_000 }); + await expect.poll(() => remoteRef(git, "main"), { timeout: 30_000 }).toBe(baseCommit); + await expect.poll(() => remoteRef(git, taskBranch), { timeout: 30_000 }).toBe(taskCommit); + } finally { + await apiClient.e2eReset(seedData.workspaceId, [seedData.workflowId]).catch(() => undefined); + if (repositoryID) await removeTestRepository(apiClient, repositoryID); + fixture.cleanup(); + } + }); +}); diff --git a/apps/web/hooks/domains/session/use-session-git.ts b/apps/web/hooks/domains/session/use-session-git.ts index 6286e4d024..6a8986ea06 100644 --- a/apps/web/hooks/domains/session/use-session-git.ts +++ b/apps/web/hooks/domains/session/use-session-git.ts @@ -38,6 +38,7 @@ export type PerRepoOperationResult = { success: boolean; output: string; error?: string; + error_code?: string; }; /** @@ -284,6 +285,7 @@ function aggregatePerRepoResults( operation, output: only.output, error: only.error, + error_code: only.error_code, }; } const allSucceeded = perRepo.every((r) => r.success); @@ -297,6 +299,7 @@ function aggregatePerRepoResults( operation, output: joined, error: firstFailure?.error, + error_code: firstFailure?.error_code, per_repo: perRepo, }; } @@ -336,6 +339,7 @@ async function fanOutAcrossRepositoryWaves( success: result.success, output: result.output, error: result.error, + error_code: result.error_code, })), operation, ); diff --git a/apps/web/hooks/use-git-operations.test.ts b/apps/web/hooks/use-git-operations.test.ts index 9c59011f6c..5d4092e3c3 100644 --- a/apps/web/hooks/use-git-operations.test.ts +++ b/apps/web/hooks/use-git-operations.test.ts @@ -1,6 +1,7 @@ import { describe, expect, it, vi } from "vitest"; import { buildGitOperationCallbacks, + getLocalizedGitOperationError, getChangeRequestTerminology, repositoryScopePayload, } from "./use-git-operations"; @@ -21,6 +22,32 @@ describe("getChangeRequestTerminology", () => { }); }); +describe("getLocalizedGitOperationError", () => { + it.each([ + [ + "empty_remote_remote_changed", + "The remote changed before the base branch was published. Refresh the task and try again.", + ], + [ + "empty_remote_base_publish_failed", + "The empty remote base branch could not be published. Check your Git access and try again.", + ], + [ + "empty_remote_branch_publish_failed", + "The base branch was published, but the task branch was not. Try Push again.", + ], + ])("maps %s to localized recovery copy", (errorCode, expected) => { + expect(getLocalizedGitOperationError(errorCode, "raw git output")).toBe(expected); + }); + + it("keeps unknown errors and falls back when no raw message exists", () => { + expect(getLocalizedGitOperationError("other_error", "provider details")).toBe( + "provider details", + ); + expect(getLocalizedGitOperationError("other_error")).toBeUndefined(); + }); +}); + describe("repository scope payloads", () => { it("keeps an explicit empty repository name", () => { expect(repositoryScopePayload("")).toEqual({ repo: "" }); diff --git a/apps/web/hooks/use-git-operations.ts b/apps/web/hooks/use-git-operations.ts index 0c2ec81e24..02cf755c67 100644 --- a/apps/web/hooks/use-git-operations.ts +++ b/apps/web/hooks/use-git-operations.ts @@ -24,10 +24,27 @@ export interface PRCreateResult { provider?: string; output?: string; error?: string; + error_code?: string; linked?: boolean; association_error?: string; } +export function getLocalizedGitOperationError( + errorCode?: string, + fallback?: string, +): string | undefined { + switch (errorCode) { + case "empty_remote_remote_changed": + return t("common:emptyRemoteRemoteChanged"); + case "empty_remote_base_publish_failed": + return t("common:emptyRemoteBasePublishFailed"); + case "empty_remote_branch_publish_failed": + return t("common:emptyRemoteBranchPublishFailed"); + default: + return fallback; + } +} + export function getChangeRequestTerminology(provider?: string) { return provider?.toLowerCase() === "gitlab" ? { longName: "Merge Request", shortName: "MR" } diff --git a/apps/web/src/locales/en/common.json b/apps/web/src/locales/en/common.json index 32631433f5..3aec46c0a7 100644 --- a/apps/web/src/locales/en/common.json +++ b/apps/web/src/locales/en/common.json @@ -176,6 +176,9 @@ "githubCliNotAuthenticated": "GitHub CLI not authenticated", "gitOpAmendCommit": "Amend commit", "gitOpCommit": "Commit", + "emptyRemoteRemoteChanged": "The remote changed before the base branch was published. Refresh the task and try again.", + "emptyRemoteBasePublishFailed": "The empty remote base branch could not be published. Check your Git access and try again.", + "emptyRemoteBranchPublishFailed": "The base branch was published, but the task branch was not. Try Push again.", "gitOperationFailedInRepos_one": "Failed in {{count}} repo: {{summary}}", "gitOperationFailedInRepos_other": "Failed in {{count}} repos: {{summary}}", "gitOperationPartialDescription_one": "{{operation}} succeeded in {{succeeded}} of {{count}} repo ({{repos}}); failed in {{summary}}", diff --git a/apps/web/src/locales/pseudo/common.json b/apps/web/src/locales/pseudo/common.json index e6652507ce..8537c9036f 100644 --- a/apps/web/src/locales/pseudo/common.json +++ b/apps/web/src/locales/pseudo/common.json @@ -176,6 +176,9 @@ "githubCliNotAuthenticated": "ĜĩţĤũƀ ĆĹĨ ńōţ àũţĥēńţĩćàţēď", "gitOpAmendCommit": "Àḿēńď ćōḿḿĩţ", "gitOpCommit": "Ćōḿḿĩţ", + "emptyRemoteRemoteChanged": "Ţĥē ŕēḿōţē ćĥàńĝēď ƀēƒōŕē ţĥē ƀàśē ƀŕàńćĥ ŵàś ƥũƀĺĩśĥēď. Ŕēƒŕēśĥ ţĥē ţàśķ àńď ţŕŷ àĝàĩń.", + "emptyRemoteBasePublishFailed": "Ţĥē ēḿƥţŷ ŕēḿōţē ƀàśē ƀŕàńćĥ ćōũĺď ńōţ ƀē ƥũƀĺĩśĥēď. Ćĥēćķ ŷōũŕ Ĝĩţ àććēśś àńď ţŕŷ àĝàĩń.", + "emptyRemoteBranchPublishFailed": "Ţĥē ƀàśē ƀŕàńćĥ ŵàś ƥũƀĺĩśĥēď, ƀũţ ţĥē ţàśķ ƀŕàńćĥ ŵàś ńōţ. Ţŕŷ Ƥũśĥ àĝàĩń.", "gitOperationFailedInRepos_one": "Ƒàĩĺēď ĩń {{count}} ŕēƥō: {{summary}}", "gitOperationFailedInRepos_other": "Ƒàĩĺēď ĩń {{count}} ŕēƥōś: {{summary}}", "gitOperationPartialDescription_one": "{{operation}} śũććēēďēď ĩń {{succeeded}} ōƒ {{count}} ŕēƥō ({{repos}}); ƒàĩĺēď ĩń {{summary}}", diff --git a/apps/web/src/locales/pt-pt/common.json b/apps/web/src/locales/pt-pt/common.json index 7101263294..388d4bda07 100644 --- a/apps/web/src/locales/pt-pt/common.json +++ b/apps/web/src/locales/pt-pt/common.json @@ -174,6 +174,9 @@ "githubCliNotAuthenticated": "A CLI do GitHub não está autenticada", "gitOpAmendCommit": "Corrigir commit", "gitOpCommit": "Commit", + "emptyRemoteRemoteChanged": "O repositório remoto mudou antes de o branch de base ser publicado. Atualize a tarefa e tente novamente.", + "emptyRemoteBasePublishFailed": "Não foi possível publicar o branch de base do repositório remoto vazio. Verifique o acesso Git e tente novamente.", + "emptyRemoteBranchPublishFailed": "O branch de base foi publicado, mas o branch da tarefa não foi. Tente fazer Push novamente.", "gitOpForcePush": "Push forçado", "gitOpHardReset": "Reposição hard", "gitOpMerge": "Merge", diff --git a/apps/web/src/locales/zh-cn/common.json b/apps/web/src/locales/zh-cn/common.json index 085354893b..49c0364c6d 100644 --- a/apps/web/src/locales/zh-cn/common.json +++ b/apps/web/src/locales/zh-cn/common.json @@ -176,6 +176,9 @@ "githubCliNotAuthenticated": "GitHub CLI 未通过身份验证", "gitOpAmendCommit": "修补提交", "gitOpCommit": "提交", + "emptyRemoteRemoteChanged": "远程仓库在发布基础分支前发生了变化。请刷新任务后重试。", + "emptyRemoteBasePublishFailed": "无法发布空远程仓库的基础分支。请检查 Git 访问权限后重试。", + "emptyRemoteBranchPublishFailed": "基础分支已发布,但任务分支未发布。请再次尝试 Push。", "gitOperationFailedInRepos_one": "在 {{count}} 个仓库中失败:{{summary}}", "gitOperationFailedInRepos_other": "在 {{count}} 个仓库中失败:{{summary}}", "gitOperationPartialDescription_one": "{{operation}}在 {{count}} 个仓库中的 {{succeeded}} 个成功({{repos}});失败:{{summary}}", diff --git a/apps/web/src/locales/zh-hk/common.json b/apps/web/src/locales/zh-hk/common.json index a4f2decceb..4f81d96ee7 100644 --- a/apps/web/src/locales/zh-hk/common.json +++ b/apps/web/src/locales/zh-hk/common.json @@ -176,6 +176,9 @@ "githubCliNotAuthenticated": "GitHub CLI 未通過身份驗證", "gitOpAmendCommit": "修補提交", "gitOpCommit": "提交", + "emptyRemoteRemoteChanged": "遠端儲存庫在發佈基礎分支前發生了變化。請刷新任務後重試。", + "emptyRemoteBasePublishFailed": "無法發佈空遠端儲存庫的基礎分支。請檢查 Git 存取權限後重試。", + "emptyRemoteBranchPublishFailed": "基礎分支已發佈,但任務分支未發佈。請再次嘗試 Push。", "gitOperationFailedInRepos_one": "在 {{count}} 個儲存庫中失敗:{{summary}}", "gitOperationFailedInRepos_other": "在 {{count}} 個儲存庫中失敗:{{summary}}", "gitOperationPartialDescription_one": "{{operation}}在 {{count}} 個儲存庫中的 {{succeeded}} 個成功({{repos}});失敗:{{summary}}", diff --git a/apps/web/src/locales/zh-tw/common.json b/apps/web/src/locales/zh-tw/common.json index 00f067652f..14c17d03d0 100644 --- a/apps/web/src/locales/zh-tw/common.json +++ b/apps/web/src/locales/zh-tw/common.json @@ -176,6 +176,9 @@ "githubCliNotAuthenticated": "GitHub CLI 未通過身分驗證", "gitOpAmendCommit": "修補提交", "gitOpCommit": "提交", + "emptyRemoteRemoteChanged": "遠端儲存庫在釋出基礎分支前發生了變化。請重新整理任務後重試。", + "emptyRemoteBasePublishFailed": "無法釋出空遠端儲存庫的基礎分支。請檢查 Git 存取權限後重試。", + "emptyRemoteBranchPublishFailed": "基礎分支已釋出,但任務分支未釋出。請再次嘗試 Push。", "gitOperationFailedInRepos_one": "在 {{count}} 個儲存庫中失敗:{{summary}}", "gitOperationFailedInRepos_other": "在 {{count}} 個儲存庫中失敗:{{summary}}", "gitOperationPartialDescription_one": "{{operation}}在 {{count}} 個儲存庫中的 {{succeeded}} 個成功({{repos}});失敗:{{summary}}", diff --git a/docs/decisions/2026-08-25-required-worktree-refresh-fails-closed.md b/docs/decisions/2026-08-25-required-worktree-refresh-fails-closed.md index 57450e2390..fa56d43793 100644 --- a/docs/decisions/2026-08-25-required-worktree-refresh-fails-closed.md +++ b/docs/decisions/2026-08-25-required-worktree-refresh-fails-closed.md @@ -1,5 +1,10 @@ # ADR-2026-08-25-required-worktree-refresh-fails-closed: Required Worktree Refresh Fails Closed +> Amended by +> [ADR-2026-08-30-empty-remote-bootstrap-publication](2026-08-30-empty-remote-bootstrap-publication.md): +> an authenticated remote that advertises zero refs uses a marked local baseline. +> Launch still performs no remote mutation. + **Status:** accepted **Date:** 2026-08-25 **Area:** backend, security, operations @@ -80,4 +85,3 @@ worktree selection. Neither boundary can prevent launch on stale state. Rejected. A reset can discard local-only commits. Kandev can select a safe containing ref or stop without mutating user history. - diff --git a/docs/decisions/2026-08-30-empty-remote-bootstrap-publication.md b/docs/decisions/2026-08-30-empty-remote-bootstrap-publication.md new file mode 100644 index 0000000000..fcb143d898 --- /dev/null +++ b/docs/decisions/2026-08-30-empty-remote-bootstrap-publication.md @@ -0,0 +1,55 @@ +# ADR-2026-08-30-empty-remote-bootstrap-publication: Keep Empty Remote Bootstrap Local Until Publication + +**Status:** accepted +**Date:** 2026-08-30 +**Area:** backend, frontend, protocol, security + +## Context + +Git can clone a remote repository that has no refs. The resulting checkout has an unborn branch and no commit that can anchor a task worktree. + +Kandev previously treated the missing base as a required-refresh error. This behavior stopped the agent before creation of the first project files. + +Kandev can create a local baseline commit, but remote publication needs a separate authority. Clone credentials can be read-only, and task launch is not publication consent. + +## Decision + +Kandev treats an authenticated zero-ref advertisement as an empty-remote state. It does not treat this result as stale local fallback. + +Kandev creates a deterministic empty baseline commit and a local marker ref under the repository lock. It creates the task worktree from that local baseline. + +Task launch, resume, and worktree recreation never publish the baseline. They do not call a provider mutation API. + +An explicit Push or Create PR action can publish the baseline. The action uses task runtime Git credentials and pushes the baseline before the task branch. + +The baseline push never uses force. If another actor initializes the remote first, Kandev stops and preserves both histories. + +Kandev identifies the baseline through an exact local marker ref. It does not infer bootstrap ownership from commit metadata or tree contents. + +## Consequences + +- Users can start isolated task worktrees for empty remote repositories. +- Read-only clone access remains sufficient for local task work. +- Remote mutation occurs only after an explicit publication action. +- Push and change-request paths must understand the local marker contract. +- A base push can succeed before a task-branch push fails. Kandev reports this partial result and preserves the task branch. +- Concurrent initializers can create a recoverable history conflict. Kandev never resolves that conflict with force or automatic history changes. +- The decision narrows the zero-ref case in the required-refresh fail-closed rule. Authentication, network, timeout, and missing-branch errors still fail closed. + +## Alternatives Considered + +### Publish an initial commit during task launch + +Rejected. Task launch does not prove write authority or user intent to change the remote. + +### Create an orphan task branch without a base + +Rejected. The remote still lacks a change-request base. The first feature push can also become the unintended default branch. + +### Initialize the remote through each provider API + +Rejected. This path duplicates the provider-neutral Git credential boundary. It also excludes pasted Git remotes. + +### Keep rejecting empty remotes with a clearer error + +Rejected. Kandev can create safe local state and delay the external write until an explicit action. diff --git a/docs/decisions/INDEX.md b/docs/decisions/INDEX.md index ab2ca9c627..eec80cdfd5 100644 --- a/docs/decisions/INDEX.md +++ b/docs/decisions/INDEX.md @@ -217,5 +217,6 @@ Read individual ADRs for full context. Create new ones via `/record decision` or | 2026-08-27-mixed-git-change-facets | [Preserve mixed Git changes as path facets](2026-08-27-mixed-git-change-facets.md) | accepted | backend, agentctl, frontend, protocol | 2026-08-27 | | 2026-08-28-bind-github-auto-merge-attempts-to-reviewed-head | [Bind GitHub Auto-Merge Attempts to the Reviewed Head](2026-08-28-bind-github-auto-merge-attempts-to-reviewed-head.md) | accepted | backend, frontend, protocol, security, GitHub | 2026-08-28 | | 2026-08-30-context-reset-quiesces-active-turn | [Quiesce Active Turns Before Context Reset](2026-08-30-context-reset-quiesces-active-turn.md) | accepted | backend, workflow | 2026-08-30 | +| 2026-08-30-empty-remote-bootstrap-publication | [Keep Empty Remote Bootstrap Local Until Publication](2026-08-30-empty-remote-bootstrap-publication.md) | accepted | backend, frontend, protocol, security | 2026-08-30 | | 2026-08-30-bound-untracked-dependency-enumeration | [Bound Untracked Dependency Enumeration](2026-08-30-bound-untracked-dependency-enumeration.md) | accepted | backend | 2026-08-30 | | 2026-08-30-e2e-browser-cache | [Cache host-runner E2E browser provisioning](2026-08-30-e2e-browser-cache.md) | accepted | infra, workflow | 2026-08-30 | diff --git a/docs/plans/empty-remote-repositories/plan.md b/docs/plans/empty-remote-repositories/plan.md new file mode 100644 index 0000000000..f2f8462d84 --- /dev/null +++ b/docs/plans/empty-remote-repositories/plan.md @@ -0,0 +1,133 @@ +--- +created: 2026-08-30 +status: implemented +requirements: + - REQ-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001 + - REQ-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002 + - REQ-WORKSPACES-WORKTREE-BASE-REFRESH-001 +system_design: + - ../../specs/workspaces/system-design/empty-remote-repositories.md + - ../../specs/workspaces/system-design/worktree-base-refresh.md +legacy_specs: [] +--- + +# Implementation Plan: Empty Remote Repositories + +## Overview + +This package lets Kandev launch task worktrees from empty remote repositories. It keeps remote publication behind existing explicit Push and Create PR actions. + +Implementation starts with typed remote-state evidence and a marked local baseline. The Git publication flow then consumes that baseline through task runtime credentials. + +Frontend error mapping, desktop and mobile evidence, and public documentation complete the delivery package. + +## Scope + +### In scope + +- Classify an authenticated zero-ref advertisement as an empty remote. +- Create a deterministic empty local baseline and exact marker ref. +- Create normal task worktrees from the local baseline. +- Publish the baseline before the task branch during explicit Push and Create PR actions. +- Preserve local and remote history when another actor initializes the remote. +- Show localized recovery errors through existing desktop and mobile Changes surfaces. +- Document empty-remote launch and first publication. + +### Out of scope + +- Create a hosted repository. +- Add project templates or initial files. +- Publish a remote ref during task launch. +- Force, reset, merge, or rebase during bootstrap recovery. +- Add change-request support for another provider. +- Add a new page, dialog, drawer, setting, or database column. + +## Technical approach + +### Remote-state evidence and local baseline + +Add a typed `RemoteRefState` result to strict clone and refresh boundaries. Carry `has_refs`, `empty`, or `unknown` into the worktree request. + +Add `internal/gitbootstrap` for the deterministic empty commit and marker-ref contract. Create the base and marker refs in one local ref transaction. + +Update `internal/worktree.Manager` to accept only authenticated `empty` evidence. Create the marked baseline under the existing repository lock before normal branch planning. + +Keep non-empty missing-branch, authentication, network, timeout, cancellation, and ancestry errors fail-closed. + +### Explicit first publication + +Add one `GitOperator` helper that validates the marker and advertises the selected remote with task runtime credentials. + +If the remote remains empty, push the marked base without force. Then use the existing task-branch push path. + +Reuse the helper in ordinary Push and Create PR. Call provider change-request creation only after both refs exist. + +Return bounded error codes for a changed remote, failed base publication, and failed task-branch publication after base success. + +### User-visible recovery + +Extend the shared Git operation result types with the bounded error codes. Map them to localized Changes toasts. + +Reuse the existing Changes split button, change-request dialog, mobile task layout, and mobile menu treatment. Add no new responsive composition. + +Add English, Portuguese, Simplified Chinese, and Traditional Chinese catalog entries. Generate both Traditional Chinese variants through the repository script. + +### End-to-end evidence + +Add a disposable empty Git remote fixture. Create a task through the normal task flow and make one project change. + +The desktop scenario proves launch, commit, Push, base-first publication, and task-branch publication. The phone scenario proves that the existing Changes touch path reaches the same result. + +The nearest mobile exemplar is the existing task layout and responsive Changes menu. The workflow uses the current scroll owner, safe-area handling, and touch targets. + +### Public documentation + +Update the task workflow guides with the empty-remote behavior and publication boundary. Correct the existing local-repository text that still describes an unborn `main` branch. + +Classify both pages as how-to guides. Keep provider credentials and recovery limits visible beside the relevant steps. + +## Tests + +- `AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.1` and `001.6`: strict refresh tests distinguish zero refs from missing branch and unavailable remote. +- `AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.2` through `001.5`: real-Git worktree tests inspect the empty tree, marker, branch, and remote refs. +- `AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.7`: multi-repository preparation tests isolate the marker and baseline. +- `AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.1` through `002.4`: `GitOperator` tests prove base-first Push and Create PR without force. +- `AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.5` through `002.7`: race and partial-result tests prove safe recovery and stable error codes. +- `AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.9`: provider tests prove that change-request creation starts after both pushes. +- `AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.8`: worktree tests prove that only typed zero-ref evidence permits the marked baseline. + +## E2E tests + +- `apps/web/e2e/tests/git/empty-remote-repository.spec.ts` covers task launch, commit, Push, remote `main`, and the task branch. +- `apps/web/e2e/tests/git/mobile-empty-remote-repository.spec.ts` covers the same Push outcome through the phone Changes menu. +- The mobile scenario uses the configured `mobile-chrome` Pixel 5 project. It asserts the user result, not only control visibility. + +## Work orders + +- [x] [Task 01: Seed Empty Remote Worktrees](task-01-seed-empty-remote-worktrees.md) +- [x] [Task 02: Publish the Empty Remote Base](task-02-publish-empty-remote-base.md) +- [x] [Task 03: Surface Publication Recovery](task-03-surface-publication-recovery.md) +- [x] [Task 04: Prove the Empty Remote Workflow](task-04-prove-empty-remote-workflow.md) +- [x] [Task 05: Document the Empty Remote Workflow](task-05-document-empty-remote-workflow.md) + +## Verification results + +Completed. + +- Task 01: `go test ./internal/gitbootstrap ./internal/repoclone ./internal/worktree ./internal/orchestrator/executor` (954 tests passed). +- Task 02: `go test ./internal/agentctl/server/process ./internal/agentctl/server/api ./internal/agent/handlers ./internal/orchestrator/handlers` (1,573 tests passed). +- Task 03: focused Vitest suite (22 tests passed), `pnpm run i18n:check`, and `pnpm run typecheck` passed. +- Task 04: desktop and `mobile-chrome` Playwright scenarios passed. +- Task 05: public-doc tests (61 passed), public-doc validation (41 pages), and `git diff --check -- docs/public` passed. +- Repository specification lint passed with `python3 scripts/lint-spec-files.py --all`. +- Review round: marker retirement, marked-base recovery, base mismatch, and credential-safe probe regressions passed; backend lint reports 0 issues. +- Review fixup coverage: absence-lease publication, immutable baseline refspec, post-publication race detection, local-baseline recreation, refreshed local-base fallback, deterministic Git identity, stdout/stderr separation, and credential-safe diagnostics are covered by focused regressions. + +## Risks + +- A weak empty-remote probe can confuse a missing branch or credential error with zero refs. +- Marker heuristics can publish user history. Implementation must compare exact refs. +- Another actor can initialize the remote between advertisement and base push. +- Baseline publication can succeed before task-branch publication fails. +- Provider and executor credential routes can expose different read and write authority. +- Multi-repository task roots can route a marker or Push to the wrong repository without exact scoping. diff --git a/docs/plans/empty-remote-repositories/task-01-seed-empty-remote-worktrees.md b/docs/plans/empty-remote-repositories/task-01-seed-empty-remote-worktrees.md new file mode 100644 index 0000000000..8659ab3f0e --- /dev/null +++ b/docs/plans/empty-remote-repositories/task-01-seed-empty-remote-worktrees.md @@ -0,0 +1,91 @@ +--- +id: "01-seed-empty-remote-worktrees" +title: "Seed Empty Remote Worktrees" +status: done +wave: 1 +depends_on: [] +plan: "plan.md" +requirements: + - REQ-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001 + - REQ-WORKSPACES-WORKTREE-BASE-REFRESH-001 +acceptance_criteria: + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.1 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.2 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.3 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.4 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.5 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.6 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.7 + - AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.8 +system_design: + - ../../specs/workspaces/system-design/empty-remote-repositories.md + - ../../specs/workspaces/system-design/worktree-base-refresh.md +--- + +# Task 01: Seed Empty Remote Worktrees + +## Summary + +Add typed empty-remote evidence and a deterministic local baseline. Create normal task worktrees from that baseline without a remote write. + +## In scope + +- Add a typed remote-ref state to strict clone and refresh results. +- Add the shared deterministic baseline and marker-ref contract. +- Seed the local base under the repository lock. +- Preserve required-refresh failures for every unproven empty state. +- Cover initial launch, recreation, and multi-repository isolation. + +## Out of scope + +- Push a remote ref. +- Change agentctl Push or Create PR. +- Add frontend copy. + +## Acceptance + +- Authenticated zero-ref evidence creates one empty marked baseline and a normal task worktree. +- Missing branch, authentication, network, timeout, and unknown states do not create a baseline. +- Launch and recreation leave the remote unchanged, including multi-repository preparation. + +## Verification + +```bash +cd apps/backend && go test ./internal/gitbootstrap ./internal/repoclone ./internal/worktree ./internal/orchestrator/executor +``` + +## Files likely touched + +- `apps/backend/internal/gitbootstrap/` +- `apps/backend/internal/repoclone/clone.go` +- `apps/backend/internal/repoclone/clone_test.go` +- `apps/backend/internal/orchestrator/executor/executor_resume.go` +- `apps/backend/internal/orchestrator/executor/executor_resume_clone_transport_test.go` +- `apps/backend/internal/worktree/worktree.go` +- `apps/backend/internal/worktree/manager_git.go` +- `apps/backend/internal/worktree/manager_lifecycle.go` +- `apps/backend/internal/worktree/manager_empty_remote_test.go` + +## Dependencies + +None. + +## Risks + +- The provider-managed refresh callback needs typed evidence without weakening exact credential scope. +- Ref creation must remain atomic under concurrent task launches. +- The commit must remain deterministic across repeated clones that use the same Git object format. + +## Parallelism + +`sequential` + +## Inputs + +- `REQ-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001` +- Empty-remote design sections for classification, baseline, launch, persistence, and security. +- Existing strict-refresh and local initial-commit tests. + +## Results + +Completed. Added typed remote-ref-state propagation, deterministic local baseline creation, marker validation, local-origin probing, and conflict-safe launch/recreation behavior. The focused backend suite passed: `go test ./internal/gitbootstrap ./internal/repoclone ./internal/worktree ./internal/orchestrator/executor` (954 tests). diff --git a/docs/plans/empty-remote-repositories/task-02-publish-empty-remote-base.md b/docs/plans/empty-remote-repositories/task-02-publish-empty-remote-base.md new file mode 100644 index 0000000000..e9bcf0ded7 --- /dev/null +++ b/docs/plans/empty-remote-repositories/task-02-publish-empty-remote-base.md @@ -0,0 +1,91 @@ +--- +id: "02-publish-empty-remote-base" +title: "Publish the Empty Remote Base" +status: done +wave: 2 +depends_on: + - "01-seed-empty-remote-worktrees" +plan: "plan.md" +requirements: + - REQ-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002 +acceptance_criteria: + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.1 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.2 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.3 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.4 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.5 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.6 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.7 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.9 +system_design: + - ../../specs/workspaces/system-design/empty-remote-repositories.md +--- + +# Task 02: Publish the Empty Remote Base + +## Summary + +Publish the marked base before the task branch during explicit Push and Create PR actions. Stop safely when the remote changes or publication fails. + +## In scope + +- Validate the exact marker and task base branch in `GitOperator`. +- Advertise the target remote through task runtime credentials. +- Publish the marked base without force before the current branch. +- Reuse the helper in Push and Create PR. +- Return bounded race and partial-result error codes. +- Delay provider change-request creation until both refs exist. + +## Out of scope + +- Publish during task launch. +- Reconcile changed remote history automatically. +- Change remote-contribution and fork destination rules. +- Add another provider API. + +## Acceptance + +- Push and Create PR initialize a still-empty remote in base-first order. +- A changed remote stops bootstrap without force or local-history loss. +- Failures identify the publication phase and leave the task branch available for retry. + +## Verification + +```bash +cd apps/backend && go test ./internal/agentctl/server/process ./internal/agentctl/server/api ./internal/orchestrator/handlers +``` + +## Files likely touched + +- `apps/backend/internal/gitbootstrap/` +- `apps/backend/internal/agentctl/server/process/git.go` +- `apps/backend/internal/agentctl/server/process/git_empty_remote.go` +- `apps/backend/internal/agentctl/server/process/git_empty_remote_test.go` +- `apps/backend/internal/agentctl/server/process/git_pr_providers_test.go` +- `apps/backend/internal/agentctl/server/api/git.go` +- `apps/backend/internal/orchestrator/handlers/git_handlers.go` +- `apps/backend/internal/orchestrator/handlers/git_handlers_test.go` + +## Dependencies + +- Task 01 supplies the marker and deterministic baseline contract. + +## Risks + +- A non-atomic base-first flow can leave a published base after task-branch failure. +- The ordinary Push path has no explicit base argument and must use the repository-scoped task base. +- Multi-repository and contribution remotes must not share bootstrap state. + +## Parallelism + +`sequential` + +## Inputs + +- `REQ-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002` +- Empty-remote design sections for publication, races, change requests, and security. +- Existing Push, Create PR, and credential-environment tests. + +## Results + +Completed. Push and Create PR now validate and publish the marked base before the task branch, retire the marker after a verified base publication, recover when unrelated refs coexist with the marked base, reject mismatched PR bases before any push, stop on remote races, preserve retryable partial results, and defer provider creation until both refs exist. The first base push uses an absence lease and an immutable baseline commit refspec. A post-push advertisement and local marker revalidation retain the marker and all remote refs when a race is detected, so the task branch is not published accidentally. Recreate and local empty-probe race paths restore from the verified local baseline without requiring `origin/`. Probe failures return bounded credential-safe errors, and baseline commits ignore inherited Git identity variables. The original focused backend suite passed: `go test ./internal/agentctl/server/process ./internal/agentctl/server/api ./internal/agent/handlers ./internal/orchestrator/handlers` (1,573 tests). The review-round process suite passed: `go test ./internal/agentctl/server/process` (733 tests), including the new regressions. The focused worktree, repoclone, and gitbootstrap regressions also pass. diff --git a/docs/plans/empty-remote-repositories/task-03-surface-publication-recovery.md b/docs/plans/empty-remote-repositories/task-03-surface-publication-recovery.md new file mode 100644 index 0000000000..3bbdaf2bcc --- /dev/null +++ b/docs/plans/empty-remote-repositories/task-03-surface-publication-recovery.md @@ -0,0 +1,86 @@ +--- +id: "03-surface-publication-recovery" +title: "Surface Publication Recovery" +status: done +wave: 3 +depends_on: + - "02-publish-empty-remote-base" +plan: "plan.md" +requirements: + - REQ-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002 +acceptance_criteria: + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.5 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.6 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.7 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.8 +system_design: + - ../../specs/workspaces/system-design/empty-remote-repositories.md +--- + +# Task 03: Surface Publication Recovery + +## Summary + +Map empty-remote publication error codes to localized recovery messages. Reuse the current desktop and mobile Changes feedback surfaces. + +## In scope + +- Carry `error_code` through shared Git and change-request result types. +- Map the three bounded empty-remote errors to translated toast text. +- Add required locale keys in all supported catalogs. +- Cover Push and Create PR error mapping with focused frontend tests. + +## Out of scope + +- Add a new visual surface or responsive composition. +- Change Push, Create PR, or Git graph behavior. +- Add a persistent recovery state. + +## Acceptance + +- A changed remote tells the user to reconcile remote history before retrying. +- Base and task-branch publication failures state which refs exist and which work remains local. +- Desktop and mobile use the same action state and localized result mapping. + +## Verification + +```bash +cd apps && pnpm install --frozen-lockfile +pnpm --filter @kandev/web test -- hooks/use-git-operations.test.ts components/task/changes-panel-hooks.test.ts +pnpm --filter @kandev/web i18n:check +``` + +## Files likely touched + +- `apps/web/hooks/use-git-operations.ts` +- `apps/web/hooks/use-git-operations.test.ts` +- `apps/web/components/task/changes-panel-hooks.ts` +- `apps/web/components/task/changes-panel-hooks.test.ts` +- `apps/web/src/locales/en/common.json` +- `apps/web/src/locales/pt-pt/common.json` +- `apps/web/src/locales/zh-cn/common.json` +- `apps/web/src/locales/zh-hk/common.json` +- `apps/web/src/locales/zh-tw/common.json` + +## Dependencies + +- Task 02 defines the bounded backend error codes and result semantics. + +## Risks + +- Raw Git output can bypass translated recovery text if one Changes handler ignores `error_code`. +- Create PR and ordinary Push use related but different response types. + +## Parallelism + +`sequential` + +## Inputs + +- `AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.5` through `002.8` +- Existing Changes toast and mobile menu behavior. +- The complete i18n catalog contract. + +## Results + +Completed. Bounded publication error codes now flow through Git and change-request results into localized desktop and mobile Changes feedback. The focused frontend suite passed (22 tests), all locale checks passed, and web typecheck passed. diff --git a/docs/plans/empty-remote-repositories/task-04-prove-empty-remote-workflow.md b/docs/plans/empty-remote-repositories/task-04-prove-empty-remote-workflow.md new file mode 100644 index 0000000000..ea14bcebe5 --- /dev/null +++ b/docs/plans/empty-remote-repositories/task-04-prove-empty-remote-workflow.md @@ -0,0 +1,87 @@ +--- +id: "04-prove-empty-remote-workflow" +title: "Prove the Empty Remote Workflow" +status: done +wave: 4 +depends_on: + - "03-surface-publication-recovery" +plan: "plan.md" +requirements: + - REQ-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001 + - REQ-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002 +acceptance_criteria: + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.1 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.4 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.5 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.1 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.8 +system_design: + - ../../specs/workspaces/system-design/empty-remote-repositories.md +--- + +# Task 04: Prove the Empty Remote Workflow + +## Summary + +Add desktop and phone Playwright scenarios for empty-remote task launch and Push. Inspect the disposable remote to prove base-first publication. + +## In scope + +- Add a disposable empty Git remote fixture and cleanup. +- Start a task from that remote through the normal task workflow. +- Create and commit one project change. +- Push through the desktop Changes action and inspect both remote refs. +- Push through the phone Changes menu and prove the same outcome. + +## Out of scope + +- Call only APIs without a user-facing assertion. +- Add a new Changes control. +- Use a live provider account or developer repository. +- Test provider API change-request creation through Playwright. + +## Acceptance + +- The task reaches an agent-ready state instead of launch failure. +- Desktop Push publishes the empty base before the task branch. +- The phone Changes path completes the same publication with existing touch controls. + +## Verification + +```bash +(cd apps && pnpm install --frozen-lockfile) +(cd apps/web && pnpm e2e:run tests/git/empty-remote-repository.spec.ts) +(cd apps/web && pnpm e2e:run --project mobile-chrome tests/git/mobile-empty-remote-repository.spec.ts) +``` + +## Files likely touched + +- `apps/web/e2e/helpers/empty-remote-repository.ts` +- `apps/web/e2e/tests/git/empty-remote-repository.spec.ts` +- `apps/web/e2e/tests/git/mobile-empty-remote-repository.spec.ts` + +## Dependencies + +- Task 01 enables launch from the empty remote. +- Task 02 enables base-first publication. +- Task 03 provides user-visible recovery messages. + +## Risks + +- The worker-scoped E2E backend requires disposable remote and repository cleanup after failure. +- The mobile project discovers only files with the `mobile-` prefix. +- The test must wait for session state and Git events instead of fixed delays. + +## Parallelism + +`sequential` + +## Inputs + +- Desktop and mobile behavior in the empty-remote design. +- The E2E fixture state and cleanup rules. +- Existing Git Changes Playwright patterns. + +## Results + +Completed. Added a disposable bare-remote fixture and desktop/mobile scenarios that prove launch without remote mutation, local commit, base-first Push, and both published refs. The desktop scenario and `mobile-chrome` scenario each passed. diff --git a/docs/plans/empty-remote-repositories/task-05-document-empty-remote-workflow.md b/docs/plans/empty-remote-repositories/task-05-document-empty-remote-workflow.md new file mode 100644 index 0000000000..00cc863fe4 --- /dev/null +++ b/docs/plans/empty-remote-repositories/task-05-document-empty-remote-workflow.md @@ -0,0 +1,82 @@ +--- +id: "05-document-empty-remote-workflow" +title: "Document the Empty Remote Workflow" +status: done +wave: 5 +depends_on: + - "04-prove-empty-remote-workflow" +plan: "plan.md" +requirements: + - REQ-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001 + - REQ-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002 +acceptance_criteria: + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.5 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.1 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.2 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.3 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.5 + - AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.8 +system_design: + - ../../specs/workspaces/system-design/empty-remote-repositories.md +--- + +# Task 05: Document the Empty Remote Workflow + +## Summary + +Update the public task how-to guides with empty-remote launch, first publication, credentials, and race recovery. Correct the stale local-repository initial-commit statement. + +## In scope + +- Explain that task launch creates only a local empty baseline. +- Explain that Push or Create PR publishes the base before the task branch. +- Explain credential requirements and changed-remote recovery. +- Correct the local new-repository guide to describe its real empty initial commit. + +## Out of scope + +- Add a new public page or navigation entry. +- Document implementation symbols or marker refs. +- Change screenshots. + +## Acceptance + +- The how-to guides describe the launch and publication boundary without implementation terms. +- The recovery text tells users to reconcile a remote that another actor initialized. +- The local and remote empty-repository descriptions no longer contradict the product contract. + +## Verification + +```bash +node --test scripts/validate-public-docs.test.mjs +node scripts/validate-public-docs.mjs +git diff --check -- docs/public +``` + +## Files likely touched + +- `docs/public/tasks-and-workflows.md` +- `docs/public/use-kandev.md` + +## Dependencies + +- Task 04 proves the final user workflow that the guides describe. + +## Risks + +- The current guide uses “empty repository” for both a local repository and an empty remote. +- Provider credentials differ between clone access and task runtime publication. + +## Parallelism + +`sequential` + +## Inputs + +- Empty-remote requirements and design. +- Public task workflow guides. +- Existing local-repository requirements. + +## Results + +Completed. Updated the public task workflow and usage guides with the local-only launch boundary, credential requirements, base-first publication, and recovery behavior. Public documentation tests and validation passed (61 tests, 41 pages), with no whitespace errors. diff --git a/docs/public/tasks-and-workflows.md b/docs/public/tasks-and-workflows.md index 9f48e19202..39ba8ab440 100644 --- a/docs/public/tasks-and-workflows.md +++ b/docs/public/tasks-and-workflows.md @@ -65,7 +65,7 @@ Use **New Task** in the sidebar. In an open task, the **Task** split button also | Source | Use it for | Important behavior | | ---------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | **Repo** | A configured, discovered, or new local repository | Select a named branch policy or a raw base branch for each repository row. A policy creates a fresh branch from its saved base and uses its branch template. For a single-row new task, **Create new repository** initializes an empty `main` repository in a parent folder you choose. Add more rows for a multi-repository task. | + | **Repo** | A configured, discovered, or new local repository | Select a named branch policy or a raw base branch for each repository row. A policy creates a fresh branch from its saved base and uses its branch template. For a single-row new task, **Create new repository** initializes an empty `main` repository with one empty initial commit in a parent folder you choose. Add more rows for a multi-repository task. | | **Remote** | A remote repository | Search configured GitHub, GitLab, or Azure DevOps repositories, or paste a supported URL. A pasted URL stays editable until you press Enter; then select the branch. Anonymous, credential-free reads include public GitHub repository branches, pull requests, and issues, plus public `gitlab.com` branch discovery. Private resources and authenticated browse/write features require valid provider credentials. | | **None** | Planning, research, or work outside Git | Use a scratch workspace or an optional folder on the Kandev host. Git worktree execution and repository-aware Changes, branch, and pull-request features are unavailable. | @@ -102,7 +102,15 @@ candidate. Kandev does not switch candidates after an ambiguous started turn. If the route has no eligible candidate, wait for the current turn to settle and use the session's **Retry current agent** or **Try next agent** recovery action. -Creating a repository is available only in an unlocked, single-repository **New Task** form. Kandev rejects an existing target path, creates no initial files or commit, registers the repository in the workspace, and switches the task to a direct **Local** executor profile. If no direct Local profile is available, repository creation stays disabled. Add more repository rows only after selecting existing repositories; empty multi-repository worktrees are not supported. +Creating a repository is available only in an unlocked, single-repository **New Task** form. Kandev rejects an existing target path, creates one empty initial commit but no project files, registers the repository in the workspace, and switches the task to a direct **Local** executor profile. If no direct Local profile is available, repository creation stays disabled. Add more repository rows only after selecting existing repositories; empty multi-repository worktrees are not supported. + +### Work with an empty remote repository + +An existing local checkout or a repository selected from **Remote** can point to a remote with no refs. Kandev creates a local empty baseline so a normal **Worktree** task can start. The baseline contains no README, license, `.gitignore`, or other project files. + +Task launch, resume, and worktree recovery do not write to the remote. When the work is ready, use the existing **Changes** action to **Push** or **Create pull request**. Kandev publishes the selected base branch first, then the task branch, with the task runtime's Git credentials. Read or clone access alone is not enough to publish. + +If another person or tool initializes the remote before the first publication, Kandev stops without overwriting that history. Reconcile the remote and local task branch, then retry. If the base branch was published but the task branch failed, the task branch remains local and **Push** can be retried. On phones, use the same actions from the touch-sized **Changes** menu. > **Local changes:** creating a fresh local branch can discard dirty files only after explicit consent. Save or commit important work before approving it. diff --git a/docs/public/use-kandev.md b/docs/public/use-kandev.md index b8239cfce6..5847debaf9 100644 --- a/docs/public/use-kandev.md +++ b/docs/public/use-kandev.md @@ -151,18 +151,26 @@ Remote repository and issue/PR URLs are not added from this settings page. Use t Detected capabilities come from the installed CLI and can change after an agent upgrade or login. A model or mode shown in documentation is not guaranteed for every account. If no built-in adapter fits, **Add TUI Agent** creates a passthrough integration; passthrough has a different resume, usage, and MCP contract from an ACP-capable agent. -For the first task on an existing repository, keep the seeded **Worktree** executor profile. It creates a separate Git checkout so concurrent Kandev tasks do not edit the same working tree. A worktree is Git isolation, not operating-system isolation. Choose **Local** only when direct edits in the selected checkout are intentional. A repository initialized from **New Task** is the exception: it has no commit to support a worktree, so Kandev switches that task to a direct Local profile. See [Agents and profiles](agents-and-profiles.md) and [Executors](executors.md) before using Docker, SSH, Sprites, custom scripts, or shared infrastructure. +For the first task on an existing repository, keep the seeded **Worktree** executor profile. It creates a separate Git checkout so concurrent Kandev tasks do not edit the same working tree. A worktree is Git isolation, not operating-system isolation. Choose **Local** only when direct edits in the selected checkout are intentional. A repository initialized from **New Task** already has one empty initial commit and no project files, and Kandev selects a direct Local profile for that flow. See [Agents and profiles](agents-and-profiles.md) and [Executors](executors.md) before using Docker, SSH, Sprites, custom scripts, or shared infrastructure. ## Create and start the first task 1. Select **New Task** from the sidebar or task board. 2. Enter a specific title and a description with the expected outcome, constraints, and validation. A non-empty description enables the normal start and create-only actions. -3. Under **Repo**, select the workspace repository and base branch. To start a new project, open the repository selector, choose **Create new repository**, enter one folder name, and select its parent folder. Kandev creates an empty `main` repository with no initial commit. Select **None** only for work that genuinely needs a plain workspace directory. +3. Under **Repo**, select the workspace repository and base branch. To start a new project, open the repository selector, choose **Create new repository**, enter one folder name, and select its parent folder. Kandev creates an empty `main` repository with one empty initial commit and no project files. Select **None** only for work that genuinely needs a plain workspace directory. 4. Choose the Development workflow and an agent profile. For an existing repository, choose the Worktree executor profile. For a newly initialized repository, keep the Local profile that Kandev selects automatically. Kandev remembers compatible recent choices, so re-check them after changing repository, agent, or trust boundary. 5. Select **Start task**. Its menu also offers **Start task in plan mode** and **Create without starting agent**. On an empty description, the primary action is **Start Plan Mode**. Starting creates the task and its initial session. Workflow step configuration determines whether entry actions or later transitions start another session, inject a prompt, or stop at a human gate. With a structured ACP profile, create-only prepares the session/workspace without starting an agent turn. A passthrough/TUI profile is the exception: the backend upgrades prepare-only to a full launch because the native PTY must exist. +### Start from an empty remote + +When the selected repository's remote has no refs, Kandev creates an empty local baseline during task preparation so the agent can use the normal Worktree executor. It adds no project files and does not publish the baseline during launch, resume, or worktree recovery. + +After the agent creates and commits work, open **Changes** and choose **Push** or **Create pull request**. Kandev publishes the selected base branch before the task branch and uses the task runtime's Git credentials. Read or clone access alone does not authorize this first publication. Provider change-request creation starts only after both branches are available on the remote. + +If another actor initializes the remote first, Kandev stops without replacing that history. Reconcile the remote with the task branch before retrying. If the base was published but the task branch was not, retry **Push**; Kandev keeps the local task branch. The same flow is available from the touch-sized **Changes** menu on phones. + The dialog also supports multiple repositories, remote GitHub rows, and a single-repository **Fork a new branch** option when the Local executor is selected. Important boundaries: - Multi-repository tasks require the Worktree executor in the current task-create path. @@ -214,7 +222,7 @@ Common corrections: - If an agent is absent after installation, run **Rescan** and inspect the host terminal's `PATH`. - If a profile has no usable model or mode, authenticate the CLI, rescan, and reopen the profile. Capability probing can heal selections that an upgraded CLI removed. - If repository validation fails, use an absolute path to an existing, accessible Git working tree. Discovery roots control automatic scans only; they do not restrict an explicit path. -- If a worktree cannot be prepared, resolve dirty/conflicting branch state, remote authentication, pull errors, setup-script failures, and disk exhaustion before retrying. +- If a worktree cannot be prepared, resolve dirty/conflicting branch state, remote authentication, pull errors, setup-script failures, and disk exhaustion before retrying. If another actor initialized an empty remote, reconcile that history with the local task branch first. - If the browser did not open, use the URL printed by the launcher or start with `--headless`; do not assume port `38429` when the launcher selected a fallback. For backup, update, log, database, and recovery details, see [Operations](operations.md). For release-specific disagreement, record the version from **Settings > System > About** and compare it with the matching GitHub tag. diff --git a/docs/specs/workspaces/README.md b/docs/specs/workspaces/README.md index 03c1fe24ed..cb1677691d 100644 --- a/docs/specs/workspaces/README.md +++ b/docs/specs/workspaces/README.md @@ -33,6 +33,7 @@ Git state. - [Create a Local Repository During Task Creation](requirements/create-local-repository.md) +- [Empty Remote Repositories](requirements/empty-remote-repositories.md) - [Kanban workspace creation](requirements/creation.md) - [Workspace Deletion](requirements/deletion.md) - [Improve Kandev](requirements/improve-kandev.md) @@ -49,6 +50,7 @@ Git state. +- [Empty Remote Repositories](system-design/empty-remote-repositories.md) - [Improve Kandev](system-design/improve-kandev.md) - [Copy and Move Secrets Between Scopes](system-design/secret-scope-transfer.md) - [Branch Policies](system-design/branch-policies.md) diff --git a/docs/specs/workspaces/requirements/empty-remote-repositories.md b/docs/specs/workspaces/requirements/empty-remote-repositories.md new file mode 100644 index 0000000000..f8f83a480e --- /dev/null +++ b/docs/specs/workspaces/requirements/empty-remote-repositories.md @@ -0,0 +1,75 @@ +--- +status: draft +system: workspaces +created: 2026-08-30 +owners: + - kandev +--- + +# Empty Remote Repository Requirements + +## Overview + +The workspace system owns remote repository materialization and the Git state used for task worktrees. An empty remote repository has no commit for a task branch. + +Kandev must let a user start work without changing the remote during task launch. Kandev can initialize the remote only during an explicit publication action. + +## Terminology + +- **Empty remote:** An authenticated Git remote that advertises zero refs. +- **Local baseline:** A Kandev-created empty commit that anchors the selected base branch. +- **Bootstrap marker:** A local Kandev ref that identifies the exact local baseline commit. +- **First publication:** The first explicit Push or Create PR action that publishes the local baseline and task branch. + +## Requirements + +### REQ-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001: Empty Remote Task Launch + +**Intent:** Let users work in an empty remote repository while Kandev preserves normal task worktree isolation. + +**User story:** As a workspace user, I want to start a task from an empty remote repository, so that an agent can create the first project files. + +#### Acceptance criteria + +- **AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.1:** When an authenticated remote advertises zero refs, Kandev shall classify it as empty instead of reporting a missing base branch. +- **AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.2:** When the remote is empty, Kandev shall create one empty local baseline commit on the selected base branch. +- **AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.3:** The local baseline shall contain no user files, generated project files, README, license, or `.gitignore`. +- **AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.4:** Kandev shall create the task worktree and task branch from the local baseline through the normal worktree lifecycle. +- **AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.5:** Initial launch, resume, and worktree recreation shall not publish a ref or commit to the remote. +- **AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.6:** When Kandev cannot prove that the remote advertises zero refs, the normal required-refresh failure rules shall apply. +- **AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.7:** In a multi-repository task, Kandev shall apply empty-remote preparation only to each repository that advertises zero refs. + +### REQ-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002: Explicit First Publication + +**Intent:** Initialize the remote base branch only when the user explicitly publishes task work. + +**User story:** As a workspace user, I want Push and Create PR to initialize an empty remote safely, so that later Git and review operations use a valid base branch. + +#### Acceptance criteria + +- **AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.1:** When the user selects Push and the remote remains empty, Kandev shall publish the marked baseline to the selected base branch before it publishes the task branch. +- **AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.2:** When the user selects Create PR and the remote remains empty, Kandev shall publish the marked baseline before it publishes the task branch and creates the change request. +- **AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.3:** First publication shall use the task runtime Git credential route. Clone or read access alone shall not authorize publication. +- **AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.4:** Kandev shall never force-push the baseline branch during first publication. +- **AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.5:** When the remote gains refs before first publication, Kandev shall stop automatic initialization and preserve all local and remote history. +- **AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.6:** When baseline publication fails, Kandev shall keep the task branch local and show a credential-safe recovery error. +- **AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.7:** When baseline publication succeeds but task-branch publication fails, Kandev shall report the partial result and preserve the task branch for retry. +- **AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.8:** Desktop and mobile users shall reach first publication through the existing Changes push and change-request controls. +- **AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.9:** Provider-specific change-request creation shall begin only after both required Git refs are present on the remote. + +## Out of scope + +- Creating a hosted repository. +- Adding project templates, files, licenses, or README content. +- Publishing during task launch, resume, or worktree recreation. +- Force-pushing or deleting a remote branch during bootstrap recovery. +- Automatically merging, rebasing, or resetting when another actor initializes the remote. +- Adding change-request support for a provider that Kandev does not support. + +## Related requirements + +- [Worktree Base Refresh Requirements](worktree-base-refresh.md) + +## System design + +- [Empty Remote Repository System Design](../system-design/empty-remote-repositories.md) diff --git a/docs/specs/workspaces/requirements/worktree-base-refresh.md b/docs/specs/workspaces/requirements/worktree-base-refresh.md index ab16b62b7c..667a218967 100644 --- a/docs/specs/workspaces/requirements/worktree-base-refresh.md +++ b/docs/specs/workspaces/requirements/worktree-base-refresh.md @@ -48,7 +48,8 @@ old copy without my knowledge. - **AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.3:** When a required fetch fails because of authentication, network access, timeout, cancellation, or another Git error, Kandev shall stop worktree preparation and shall not use a stale - local fallback ref. + local fallback ref. An authenticated zero-ref advertisement is the distinct + empty-remote state defined by `REQ-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001`. - **AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.4:** When the required fetch succeeds, Kandev shall choose a start ref that contains the fetched remote base. It can preserve local-only commits only when the local base also @@ -65,6 +66,9 @@ old copy without my knowledge. during initial launch or a resume that creates or recreates a worktree, Kandev shall expose the failure through the existing durable task launch-error projection. +- **AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.8:** When authenticated refresh + proves that a remote advertises zero refs, Kandev shall use only the marked + local baseline defined by the empty-remote repository contract. ## Out of scope @@ -77,4 +81,3 @@ old copy without my knowledge. ## System design - [Worktree Base Refresh System Design](../system-design/worktree-base-refresh.md) - diff --git a/docs/specs/workspaces/system-design/empty-remote-repositories.md b/docs/specs/workspaces/system-design/empty-remote-repositories.md new file mode 100644 index 0000000000..5bd9146233 --- /dev/null +++ b/docs/specs/workspaces/system-design/empty-remote-repositories.md @@ -0,0 +1,170 @@ +--- +status: draft +system: workspaces +requirements: + - REQ-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001 + - REQ-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002 +--- + +# Empty Remote Repository System Design + +## Purpose and boundaries + +The workspace system owns repository materialization, base refs, and task worktrees. This design adds a safe path for a remote that advertises zero refs. + +The task system continues to own session launch state and launch-error presentation. The integration system continues to own provider credentials and provider change-request APIs. + +Task launch creates local Git state only. Push and Create PR remain the only actions in this design that can initialize the remote. + +## Requirement mapping + +| Acceptance criteria | Design section | +| --- | --- | +| `AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.1` | [Remote-state classification](#remote-state-classification) | +| `AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.2` through `001.4` | [Local baseline](#local-baseline) | +| `AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.5` | [Launch and recreation flow](#launch-and-recreation-flow) | +| `AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.6` | [Failure and recovery](#failure-and-recovery) | +| `AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-001.7` | [Multi-repository tasks](#multi-repository-tasks) | +| `AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.1` through `002.4` | [First publication](#first-publication) | +| `AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.5` through `002.7` | [Publication races and partial results](#publication-races-and-partial-results) | +| `AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.8` | [Desktop and mobile behavior](#desktop-and-mobile-behavior) | +| `AC-WORKSPACES-EMPTY-REMOTE-REPOSITORIES-002.9` | [Change-request creation](#change-request-creation) | + +## Components and responsibilities + +- `internal/repoclone` reports authenticated remote-ref state after clone or strict refresh. +- `internal/orchestrator/executor` carries the typed remote-ref state into repository preparation. +- `internal/worktree.Manager` creates the local baseline and normal task worktree under the repository lock. +- `internal/gitbootstrap` owns the deterministic commit contract, marker-ref format, and marker validation. +- `internal/agentctl/server/process.GitOperator` performs first publication with task runtime credentials. +- The existing Changes hooks map bounded publication error codes to translated user messages. +- Existing Changes controls remain the desktop and mobile entry points. + +## Remote-state classification + +Repository refresh returns one typed state: `has_refs`, `empty`, or `unknown`. Only an authenticated remote advertisement with zero refs produces `empty`. + +A missing requested branch on a remote with other refs is not an empty remote. Authentication, network, timeout, cancellation, and malformed-response errors produce `unknown` with a classified error. + +Managed provider refresh returns the state through its exact-scope credential callback. Host and executor refresh use the same non-interactive Git credential route as the required fetch. + +The worktree preparation contract carries the typed state with `RemoteSyncHandled`. A successful zero-ref advertisement counts as a completed required refresh. + +## Local baseline + +`internal/gitbootstrap` creates one deterministic empty commit. The commit uses an empty tree, fixed Kandev identity, fixed timestamp, and fixed message. + +The helper creates two refs in one local ref transaction: + +- `refs/heads/` points to the baseline commit. +- `refs/kandev/empty-remote/` marks the exact baseline commit. + +The marker never uses commit-message, author, timestamp, or tree heuristics. Publication requires the marker and local base ref to point to the same commit. + +The worktree manager performs this operation under its existing repository lock. If the local repository gains a real ref before the transaction, preparation stops and reevaluates normal base selection. + +The baseline command does not run repository hooks. It does not use user signing configuration. It writes no working-tree file. + +## Launch and recreation flow + +The normal refresh gate runs before worktree creation. If the result is `empty`, the manager creates or reuses the marked local baseline. + +The existing branch planner then creates the task branch and worktree from the local base. Worktree records retain the selected `BaseBranch` and generated task branch. + +Resume and recreation use the same marker validation. If a managed checkout is cloned again, the deterministic helper produces the same baseline for the same Git object format. + +No launch path calls `git push`, a provider mutation API, or a credential route with write intent. + +## First publication + +`GitOperator` checks for the marker before an ordinary Push or Create PR branch push. The operator obtains the task base branch from the existing per-repository base-branch map. + +If the marker is absent, the current Git operation does not use this feature. It follows the existing push or change-request flow. + +If the marker is valid, the operator advertises the selected remote with task runtime credentials. If the remote still has zero refs, it performs these operations: + +1. Push the marked local base to `refs/heads/` without force. +2. Push the current task branch through the existing push path. +3. Set the task branch upstream through the existing rules. + +The base publication does not use provider background credentials. It uses the same Git environment and remote authority as the user-selected task operation. + +Force Push can retain its existing task-branch behavior. The baseline push never receives a force flag. + +## Publication races and partial results + +Another actor can initialize the remote after task launch. The pre-publication advertisement detects this state before Kandev publishes the baseline. + +If the remote base equals the marked baseline, publication continues. This case makes retries idempotent after a prior baseline push. + +If the remote has other refs or a different base, Kandev does not publish the marked baseline. It fetches safe evidence when possible and returns `empty_remote_remote_changed`. + +Kandev does not merge, rebase, reset, delete, or force a ref during this recovery. The local task branch and marker remain available. + +If baseline publication fails, Kandev returns `empty_remote_base_publish_failed`. It does not start the task-branch push. + +If baseline publication succeeds but task-branch publication fails, Kandev returns `empty_remote_branch_publish_failed`. The result states that the base exists and the task branch remains local. + +## Change-request creation + +Create PR uses its requested base branch after normalization. The requested base must match the marked task base during empty-remote publication. + +The operator publishes the base first and the task branch second. It calls the existing GitHub, GitLab, Azure DevOps, or plugin provider only after both pushes succeed. + +Provider retry behavior starts after the Git refs are present. A provider API error does not remove either published ref. + +## Desktop and mobile behavior + +The feature adds no new page, dialog, drawer, or control. Desktop users use the existing Changes split button and change-request dialog. + +Phone users use the same Changes actions through the existing touch menu and task layout. The global mobile menu treatment remains the nearest shipped interaction pattern. + +Shared action handlers map publication error codes to localized recovery text. The mobile path does not depend on hover, right-click, or a desktop-only control. + +## Multi-repository tasks + +Remote-state classification and local baseline state are repository-scoped. One empty repository does not change another repository's base or marker. + +Task launch continues only after every repository completes its required preparation. Push and change-request actions continue to target one selected repository. + +## Persistence and cleanup + +The local marker ref is the durable bootstrap identity. No database migration is required. + +Worktree cleanup follows the existing task lifecycle. The canonical checkout retains the local base and marker until normal repository maintenance removes that checkout. + +If Kandev reclones an unchanged empty remote, it recreates the deterministic baseline. If the remote now has refs, normal refresh replaces the empty-remote path. + +## Security + +Read access does not grant write authority. Task launch never tests write permission and never publishes a remote ref. + +First publication uses the task runtime credential route and exact repository remote. Managed credentials retain workspace, task, session, repository, host, and path scope. + +Logs and user messages contain bounded error classes. They do not contain tokens, helper output, authenticated URLs, or unrestricted Git stderr. + +The operator validates every branch name before it constructs a Git command. The marker ref is derived only from a validated base branch. + +## Failure and recovery + +- If remote-state classification is `unknown`, required preparation fails closed. +- If a non-empty remote lacks the requested base, normal base fallback or failure behavior applies. +- If local baseline creation fails, task launch stops before worktree creation. +- If another actor initializes the remote, the user must reconcile history before publication. +- If write credentials are absent, local work remains available and publication returns the existing credential failure class. +- If only task-branch publication fails, the user can retry Push without recreating the task. + +## Observability + +Structured logs record repository identity, task identity, session identity, remote-ref state, base branch, and publication phase. Logs omit remote credentials and raw authenticated URLs. + +Preparation progress reports a bounded `empty_remote_baseline` result. Publication reports `base`, `task_branch`, or `provider` as the failed phase. + +Diagnostics expose the marker ref name and commit ID only for the selected repository. They do not include task prompts or credential helper data. + +## Related decisions + +- [Keep Empty Remote Bootstrap Local Until Publication](../../../decisions/2026-08-30-empty-remote-bootstrap-publication.md) +- [Required Worktree Refresh Fails Closed](../../../decisions/2026-08-25-required-worktree-refresh-fails-closed.md) +- [Provider-Neutral Git Credential Broker](../../../decisions/2026-07-31-provider-neutral-git-credential-broker.md) +- [Separate GitHub Automation From Task Git Credential Policy](../../../decisions/2026-07-27-task-git-credential-policy.md) diff --git a/docs/specs/workspaces/system-design/worktree-base-refresh.md b/docs/specs/workspaces/system-design/worktree-base-refresh.md index 7dd02d453a..4c68ca231f 100644 --- a/docs/specs/workspaces/system-design/worktree-base-refresh.md +++ b/docs/specs/workspaces/system-design/worktree-base-refresh.md @@ -34,6 +34,7 @@ launch. | `AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.5` | [Base-ref selection](#base-ref-selection) | | `AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.6` | [Multi-repository launch](#multi-repository-launch) | | `AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.7` | [Launch-error projection](#launch-error-projection) | +| `AC-WORKSPACES-WORKTREE-BASE-REFRESH-001.8` | [Empty remote exception](#empty-remote-exception) | ## Components and responsibilities @@ -131,6 +132,16 @@ not reset, rebase, merge, or delete a branch. Git failure classification but exclude tokens, credential helper output, and secret-bearing URLs. +## Empty remote exception + +An authenticated remote advertisement with zero refs is not a stale local +fallback. It is the typed empty-remote state defined by +[Empty Remote Repository System Design](empty-remote-repositories.md). + +This exception creates only the marked local baseline. It does not permit a +launch-time remote write or relax any authentication, network, timeout, +cancellation, missing-branch, or ancestry error. + ## Multi-repository launch The executor resolves and prepares repository specs before agent startup. If a @@ -159,8 +170,8 @@ credential configuration. - Fetch authentication, network, timeout, cancellation, and Git command errors stop required preparation. -- A missing fetched remote base stops preparation. It cannot fall back to a - local ref when refresh is required. +- A missing fetched remote base on a non-empty remote stops preparation. It + cannot fall back to a local ref when refresh is required. - A failed ancestry probe stops preparation. - A divergent base stops preparation and preserves both refs. - Disabling pull-before-worktree is the explicit offline opt-out. Kandev does