Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

14.3 KB
Raw Blame
/// The Git choices a project folder offers, and what Start would do with them.
///
/// ⚠️ **This is the phone's HALF of the desktop's `core/git_worktree.dart`**, the
/// same split `core/project_folder.dart` already makes. That file carries a
/// second half built on `dart:io` — it runs `git` itself, which is right for a
/// folder on the machine the desktop is running ON. Every machine a phone talks
/// to is remote, so the machine reads its own repository (`git_project_info`,
/// served by `cli/src/lib/gitProject.ts`) and this only parses the answer and
/// works out what to ask for. Nothing here touches a filesystem or a process.
///
/// The planning rules below ([planWorktree] and its neighbours) are ported from
/// `state/new_harness.dart` unchanged, because they decide what is SENT: a
/// phone that planned differently would make a different branch from a desktop
/// asked the same question.
library;

import 'dart:math';

import 'package:path/path.dart' as p;

import 'project_folder.dart';

class GitBranch {
  const GitBranch(
    this.ref,
    this.name, {
    this.remote = false,
    this.worktree,
    this.harness = false,
  });

  final String ref, name;
  final bool remote;

  /// Harness made this branch for a worktree.
  final bool harness;

  /// Where this local branch is checked out, when it is.
  final String? worktree;
}

class GitProjectInfo {
  const GitProjectInfo({
    this.isGit = false,
    this.branch,
    this.branches = const [],
    this.error,
    this.mainFolder,
    this.mainBranch,
    this.defaultRef,
    this.root,
  });

  factory GitProjectInfo.fromJson(Map<String, dynamic> data) => GitProjectInfo(
    isGit: data['isGit'] == true,
    branch: data['branch'] as String?,
    error: data['error'] as String?,
    mainFolder: data['mainFolder'] is String && validGitPath(data['mainFolder'])
        ? data['mainFolder'] as String
        : null,
    mainBranch: data['mainBranch'] as String?,
    defaultRef: data['defaultRef'] is String && validGitRef(data['defaultRef'])
        ? data['defaultRef'] as String
        : null,
    root: data['root'] is String && validGitPath(data['root'])
        ? data['root'] as String
        : null,
    branches: [
      for (final row in (data['branches'] as List? ?? const []))
        if (row is Map && row['ref'] is String && row['name'] is String)
          GitBranch(
            row['ref'] as String,
            row['name'] as String,
            remote: row['remote'] == true,
            worktree: row['worktree'] is String
                ? row['worktree'] as String
                : null,
            harness: row['harness'] == true,
          ),
    ],
  );

  final bool isGit;
  final String? branch, error;
  final List<GitBranch> branches;

  /// Set only for a folder inside a linked worktree: the same folder in the
  /// repository's main checkout, and the branch that checkout is on.
  final String? mainFolder, mainBranch;

  /// The remote branch new work starts from by default (`origin/HEAD`), and
  /// the checkout the folder belongs to.
  final String? defaultRef, root;

  /// Whether the machine could not answer at all, as opposed to answering
  /// "not a repository". The difference decides whether the screen offers
  /// nothing or says why.
  bool get unavailable => error != null;
}

/// What Start does with a Git project in a new worktree.
enum WorktreeStart {
  /// A new branch from the chosen base.
  newBranch,

  /// An existing local branch, checked out as it is.
  existingBranch,

  /// The branch already has a worktree: the harness starts in it.
  openWorktree,

  /// The branch is the project folder's own and cannot be checked out twice.
  unavailable,
}

class WorktreePlan {
  const WorktreePlan(this.kind, this.branch, {this.base, this.worktree});

  final WorktreeStart kind;
  final String branch;

  /// What a new branch starts from; a remote branch of the same name is tracked.
  final String? base;

  /// Where an existing worktree is.
  final String? worktree;

  bool get tracks =>
      kind == WorktreeStart.newBranch &&
      base != null &&
      base!.startsWith('refs/remotes/') &&
      base!.split('/').skip(3).join('/') == branch;
}

/// The project folder's own branch, if it is on one.
String? currentBranchRef(GitProjectInfo info) =>
    info.branch != null &&
        info.branches.any((b) => b.ref == 'refs/heads/${info.branch}')
    ? 'refs/heads/${info.branch}'
    : null;

/// Worktree starts on for a Git project with a commit to start from.
bool worktreeByDefault(GitProjectInfo info) =>
    info.isGit && info.branches.any((branch) => !branch.remote);

/// Where Start begins when no branch was chosen: new work from the default
/// branch (the local one, which Start brings up to its remote), work in the
/// folder on the branch it is on.
String? defaultBranchRef(GitProjectInfo info, {required bool worktree}) {
  if (!worktree) return currentBranchRef(info);
  final remote = info.defaultRef;
  final local = remote == null
      ? null
      : 'refs/heads/${remote.split('/').skip(3).join('/')}';
  return info.branches.any((b) => b.ref == local)
      ? local
      : remote ?? currentBranchRef(info);
}

/// The branch a worktree started from [base] is on, unless [name] was typed:
/// the default or current branch gets a new [placeholder] branch; another
/// local branch is checked out as it is, or opened in its worktree; a remote
/// branch nobody has locally becomes a local branch tracking it.
WorktreePlan planWorktree(
  GitProjectInfo info, {
  required String? base,
  required String? name,
  required String placeholder,
}) {
  GitBranch? local(String branch) =>
      info.branches.where((b) => !b.remote && b.name == branch).firstOrNull;
  // The folder's own branch cannot be checked out again: typed, it is refused;
  // picked (itself or its remote), a new branch starts from what was picked.
  WorktreePlan onLocal(GitBranch branch, {required bool chosen}) =>
      branch.name == info.branch
      ? chosen
            ? WorktreePlan(WorktreeStart.unavailable, branch.name)
            : WorktreePlan(WorktreeStart.newBranch, placeholder, base: base)
      : branch.worktree != null
      ? WorktreePlan(
          WorktreeStart.openWorktree,
          branch.name,
          worktree: branch.worktree,
        )
      : WorktreePlan(WorktreeStart.existingBranch, branch.name);
  final typed = name?.trim();
  if (typed != null && typed.isNotEmpty) {
    final existing = local(typed);
    return existing == null
        ? WorktreePlan(WorktreeStart.newBranch, typed, base: base)
        : onLocal(existing, chosen: true);
  }
  final fresh = WorktreePlan(WorktreeStart.newBranch, placeholder, base: base);
  final defaultName = info.defaultRef?.split('/').skip(3).join('/');
  if (base == null ||
      base == info.defaultRef ||
      base == 'refs/heads/$defaultName') {
    return fresh;
  }
  if (base.startsWith('refs/heads/')) {
    final branch = local(base.substring('refs/heads/'.length));
    return branch == null ? fresh : onLocal(branch, chosen: false);
  }
  final short = base.split('/').skip(3).join('/');
  final branch = local(short);
  return branch != null
      ? onLocal(branch, chosen: false)
      : WorktreePlan(WorktreeStart.newBranch, short, base: base);
}

/// With Worktree off, the new branch the folder moves to: a typed name no
/// local branch has.
String? newBranchHere(GitProjectInfo info, String? name) {
  final typed = name?.trim();
  return typed == null ||
          typed.isEmpty ||
          info.branches.any((b) => !b.remote && b.name == typed)
      ? null
      : typed;
}

/// With Worktree off, whether Start moves the folder ITSELF onto another branch — the one choice
/// that reaches every harness already working in its checkout.
///
/// ⚠️ **The desktop's condition (`state/new_harness.dart`, `create`), kept in step with it.** With
/// Worktree off the machine (`cli/src/lib/gitProject.ts`, `prepareGitProject`) makes a typed new
/// branch where the folder is and moves the folder onto it, and checks any other local branch out
/// in the folder with `git switch` once nothing there is uncommitted. Three choices move nothing,
/// so they are not counted: the branch the folder is already on; a branch with a worktree of its
/// own, which the machine opens instead, since Git will not check a branch out twice; and a remote
/// branch, which the machine refuses with Worktree off, in its own words ("Choose a local branch,
/// or turn Worktree on."). The desktop refuses that last one before its own check, so the two never
/// say different things about it.
bool switchesFolderBranch(
  GitProjectInfo info, {
  required bool worktree,
  required String? branchRef,
  required String? branchName,
}) {
  if (worktree) return false;
  if (newBranchHere(info, branchName) != null) return true;
  final ref = branchRef ?? defaultBranchRef(info, worktree: false);
  return ref != null &&
      ref.startsWith('refs/heads/') &&
      ref != currentBranchRef(info) &&
      // The desktop's `_worktreeOf`: checked out somewhere other than this folder.
      !info.branches.any(
        (branch) =>
            branch.ref == ref &&
            branch.worktree != null &&
            branch.name != info.branch,
      );
}

/// Whether [path] is the checkout at [root] or a folder inside it — what moves with the checkout
/// when its branch is switched.
///
/// Both are the machine's paths, so they are compared by POSIX rules whatever this device's own
/// are; `/code/web` holds `/code/web/api` and not `/code/website`.
bool withinCheckout(String root, String path) =>
    p.posix.equals(path, root) || p.posix.isWithin(root, path);

/// The preparation a Git project's folder gets at Start.
///
/// ⚠️ **Ported from the desktop's `state/new_harness.dart` line for line, and
/// that is the point of it.** This is the function that decides what the
/// machine is ASKED to do — make a branch, check one out, open a worktree — and
/// a phone that decided differently would answer the same question with a
/// different repository. Change it here only by changing it there too.
ProjectFolderRequest? gitFolderRequest(
  String folder,
  GitProjectInfo info, {
  required bool worktree,
  required String? branchRef,
  required String? branchName,
  required String placeholder,
}) {
  final ref = branchRef ?? defaultBranchRef(info, worktree: worktree);
  if (!worktree) {
    if (newBranchHere(info, branchName) case final name?) {
      return ProjectFolderRequest.branch(
        folder,
        'refs/heads/$name',
        newBranch: name,
      );
    }
    return ref == null ? null : ProjectFolderRequest.branch(folder, ref);
  }
  final plan = planWorktree(
    info,
    base: ref,
    name: branchName,
    placeholder: placeholder,
  );
  return switch (plan.kind) {
    WorktreeStart.openWorktree => ProjectFolderRequest.branch(
      folder,
      'refs/heads/${plan.branch}',
    ),
    WorktreeStart.existingBranch => ProjectFolderRequest.worktree(
      folder,
      branchRef: 'refs/heads/${plan.branch}',
      branchName: plan.branch,
      existingBranch: true,
    ),
    WorktreeStart.newBranch ||
    WorktreeStart.unavailable => ProjectFolderRequest.worktree(
      folder,
      branchRef: plan.base,
      branchName: plan.branch,
      placeholder: plan.branch == placeholder,
    ),
  };
}

/// Two plain words for a branch nothing has named yet — plumbing, like the
/// worktree's folder: the harness or the person names the real branch when
/// there is something to push. Mirrors cli/src/lib/agentNames.ts.
const kPlaceholderAdjectives = [
  'amber', 'bold', 'brave', 'brisk', 'calm', 'clever', 'cosmic', 'crisp', //
  'dapper', 'eager', 'fancy', 'gentle', 'glad', 'golden', 'happy', 'hidden',
  'jolly', 'keen', 'kind', 'lively', 'lucky', 'merry', 'misty', 'noble', //
  'polite', 'proud', 'quick', 'quiet', 'rapid', 'rosy', 'royal', 'rustic',
  'shiny', 'silent', 'silver', 'sleek', 'smart', 'snowy', 'solar', 'spry',
  'steady', 'sunny', 'swift', 'tidy', 'vivid', 'warm', 'witty', 'zesty',
];

const kPlaceholderNouns = [
  'badger', 'beacon', 'birch', 'bison', 'canyon', 'cedar', 'comet', 'coral',
  'crane', 'delta', 'falcon', 'fern', 'finch', 'fjord', 'fox', 'gecko', //
  'glacier', 'harbor', 'hawk', 'heron', 'ibis', 'island', 'koala', 'lagoon',
  'lark', 'lynx', 'maple', 'meadow', 'meteor', 'moose', 'nebula', 'otter', //
  'owl', 'panda', 'pebble', 'pine', 'puffin', 'quartz', 'raven', 'reef', //
  'river', 'robin', 'sparrow', 'spruce', 'tiger', 'walrus', 'willow', 'zebra',
];

/// `brave-otter`: the branch a new worktree starts on until its session has a
/// name, one none of [taken] (branch names, with or without `refs/heads/`)
/// already uses.
String placeholderBranch(Iterable<String> taken, {Random? random}) {
  final names = {
    for (final name in taken) name.replaceFirst('refs/heads/', ''),
  };
  final pick = random ?? Random();
  String draw() =>
      '${kPlaceholderAdjectives[pick.nextInt(kPlaceholderAdjectives.length)]}'
      '-${kPlaceholderNouns[pick.nextInt(kPlaceholderNouns.length)]}';
  var name = draw();
  for (var tries = 0; tries < 16 && names.contains(name); tries++) {
    name = draw();
  }
  final base = name;
  for (var suffix = 2; names.contains(name); suffix++) {
    name = '$base-$suffix';
  }
  return name;
}

/// What a typed name becomes as a branch, as editors do it: words joined by
/// `-`, and nothing `git check-ref-format` refuses. Empty when nothing is left.
String branchNameFrom(String typed) {
  var name = typed
      .trim()
      .replaceAll(RegExp(r'\s+'), '-')
      .replaceAll(RegExp(r'[\x00-\x1f\x7f~^:?*\[\\]+'), '')
      .replaceAll(RegExp(r'\.{2,}'), '.')
      .replaceAll('@{', '@')
      .replaceAll(RegExp(r'/{2,}'), '/')
      .replaceAll(RegExp(r'/[.]+'), '/')
      .replaceAll(RegExp(r'-{2,}'), '-')
      .replaceAll(RegExp(r'^[-./]+'), '');
  for (var trimmed = ''; trimmed != name;) {
    trimmed = name;
    name = name.replaceAll(RegExp(r'(\.lock|[./])$'), '');
  }
  return name == '@' ? '' : name;
}

/// A name Git accepts for a new branch, checked before Git is asked.
bool plausibleBranchName(String name) =>
    name.isNotEmpty &&
    name.length <= 255 &&
    !name.startsWith('-') &&
    !RegExp(r'[\x00-\x20\x7f~^:?*\[\\]').hasMatch(name);

bool validGitPath(String path) =>
    p.isAbsolute(path) &&
    path.length <= 4096 &&
    !RegExp(r'[\x00-\x1f\x7f]').hasMatch(path);

bool validGitRef(String ref) =>
    ref.length <= 1024 &&
    RegExp(r'^refs/(heads|remotes)/[^\s\x00-\x1f\x7f]+$').hasMatch(ref);