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.

9.5 KB
Raw Blame
/// Where a new agent's project comes from, when it is not a folder that already exists.
///
/// ⚠️ This is the phone's HALF of the desktop's `core/project_folder.dart`. That one carries a
/// second half, `prepareLocal`, which makes the folder or clones the repository with `dart:io` and
/// hands over a real path — right for a machine the desktop is running ON, and meaningless here.
/// Every machine a phone talks to is remote, so the machine does the work and this only has to say
/// what to do. Nothing in this file touches a filesystem.
///
/// The keys travel to `cli/src/lib/projectFolder.ts`, which parses them and clones. The CLI parses
/// the URL again at its end; [GitHubRepository.parse] runs here anyway so a typo is answered on the
/// screen it was typed on rather than after a round trip.
class ProjectFolderRequest {
  /// Let the machine make a fresh project folder of its own.
  const ProjectFolderRequest.newProject()
    : repository = null,
      gitSource = null,
      branchRef = null,
      branchName = null,
      existingBranch = false,
      placeholder = false,
      createsWorktree = false,
      suggestedName = null;

  /// A fresh project named after its first [task] (openharness#94): the machine makes
  /// `~/harnesses/robot-noi-chuyen-voi-gemini`, and numbers it past one that exists. A task with
  /// no words to name it by leaves the name to the machine, as [ProjectFolderRequest.newProject].
  ProjectFolderRequest.forTask(String task)
    : repository = null,
      gitSource = null,
      branchRef = null,
      branchName = null,
      existingBranch = false,
      placeholder = false,
      createsWorktree = false,
      suggestedName = taskProjectSlug(task);

  /// Let the machine clone [value] and work in the checkout.
  const ProjectFolderRequest.remote(GitHubRepository value)
    : repository = value,
      gitSource = null,
      branchRef = null,
      branchName = null,
      existingBranch = false,
      placeholder = false,
      createsWorktree = false,
      suggestedName = null;

  /// A new worktree of the repository at [source], on [branchName]: created
  /// from [branchRef], or with [existingBranch] that local branch checked out
  /// as it is. Without a name the machine makes one up.
  ///
  /// ⚠️ [placeholder] says the name was MADE UP here rather than typed, so the
  /// machine may replace it with the session's own name once the engine reports
  /// one. A name a person typed is theirs and is never replaced.
  const ProjectFolderRequest.worktree(
    String source, {
    this.branchRef,
    this.branchName,
    this.existingBranch = false,
    this.placeholder = false,
  }) : gitSource = source,
       createsWorktree = true,
       repository = null,
       suggestedName = null;

  /// The folder at [source] itself on [ref], or with [newBranch] on that new
  /// branch, made where the folder is now.
  ///
  /// ⚠️ [ref] then names the NEW branch, so a daemon too old to make one
  /// refuses the request rather than quietly starting the harness on the old
  /// branch — which is the one outcome nobody could see had happened.
  const ProjectFolderRequest.branch(
    String source,
    String ref, {
    String? newBranch,
  }) : gitSource = source,
       branchRef = ref,
       branchName = newBranch,
       existingBranch = false,
       placeholder = false,
       createsWorktree = false,
       repository = null,
       suggestedName = null;

  final GitHubRepository? repository;

  /// The folder a fresh project is named after its first task, or null to leave the name to the
  /// machine (engine and time).
  final String? suggestedName;

  /// The existing checkout a branch or worktree is taken from. Null for the two
  /// sources that have no repository yet.
  final String? gitSource;

  /// What to start from, and what to call the branch that starts there.
  final String? branchRef, branchName;

  final bool createsWorktree, existingBranch, placeholder;

  /// ⚠️ Sent INSTEAD of `cwd`, never beside it — see `AppNotifier.createAgent`. The two answer the
  /// same question, and a machine given both would have to guess which one was meant.
  ///
  /// The keys are the desktop's, byte for byte (`core/project_folder.dart`
  /// there): the same CLI parses both, and a phone inventing its own spelling
  /// would be a second dialect to keep in step.
  Map<String, String> get payload => {
    'projectSource': gitSource != null
        ? (createsWorktree ? 'worktree' : 'branch')
        : repository == null
        ? 'new'
        : 'remote',
    'gitSource': ?gitSource,
    'branchRef': ?branchRef,
    // A daemon that predates these names the worktree's branch itself.
    'branchName': ?branchName,
    if (existingBranch) 'branchMode': 'existing',
    if (placeholder) 'branchMode': 'placeholder',
    if (repository != null) 'repositoryUrl': repository!.url,
    // A made-up name: the machine numbers it past a folder that exists rather than refusing it. A
    // daemon that predates `projectNameMode` refuses a taken name instead; one that predates
    // `projectName` names the folder itself.
    'projectName': ?suggestedName,
    if (suggestedName != null) 'projectNameMode': 'suggested',
  };
}

/// How many of a first task's words name the project and the agent. The desktop's
/// `core/project_folder.dart` holds the same rule; the two apps name the same task the same way.
const _taskNameWords = 6;

/// The first line of [task], cut to its first few words — what a project named after its task, and
/// the agent in it, are called ("Robot nói chuyện với Gemini"). Null when the task has no letters or
/// digits to name anything by.
String? taskProjectTitle(String task) {
  final line = task
      .trim()
      .split('\n')
      .first
      .split(RegExp(r'\s+'))
      .where((word) => word.isNotEmpty)
      .take(_taskNameWords)
      .join(' ');
  if (!RegExp(r'[\p{L}\p{N}]', unicode: true).hasMatch(line)) return null;
  return line.length > 60 ? line.substring(0, 60).trimRight() : line;
}

/// The folder a project named after [task] gets: lowercase words joined by dashes, accents folded
/// (`robot-noi-chuyen-voi-gemini`). Null when nothing usable is left.
String? taskProjectSlug(String task) {
  final title = taskProjectTitle(task);
  if (title == null) return null;
  final slug = foldDiacritics(title)
      .toLowerCase()
      .replaceAll(RegExp(r'[^a-z0-9]+'), '-')
      .replaceAll(RegExp(r'^-+|-+$'), '');
  if (slug.isEmpty) return null;
  return slug.length > 48
      ? slug.substring(0, 48).replaceAll(RegExp(r'-+$'), '')
      : slug;
}

/// [text] with Latin letters' accents removed: Vietnamese (`đ` included), French, German,
/// Spanish, Portuguese and the like. Other scripts pass through untouched.
String foldDiacritics(String text) {
  final out = StringBuffer();
  for (final rune in text.runes) {
    final char = String.fromCharCode(rune);
    out.write(_folds[char] ?? char);
  }
  return out.toString();
}

final Map<String, String> _folds = () {
  const groups = {
    'a': 'àáảãạăằắẳẵặâầấẩẫậäåā',
    'A': 'ÀÁẢÃẠĂẰẮẲẴẶÂẦẤẨẪẬÄÅĀ',
    'e': 'èéẻẽẹêềếểễệëē',
    'E': 'ÈÉẺẼẸÊỀẾỂỄỆËĒ',
    'i': 'ìíỉĩịïī',
    'I': 'ÌÍỈĨỊÏĪ',
    'o': 'òóỏõọôồốổỗộơờớởỡợöøō',
    'O': 'ÒÓỎÕỌÔỒỐỔỖỘƠỜỚỞỠỢÖØŌ',
    'u': 'ùúủũụưừứửữựüū',
    'U': 'ÙÚỦŨỤƯỪỨỬỮỰÜŪ',
    'y': 'ỳýỷỹỵÿ',
    'Y': 'ỲÝỶỸỴŸ',
    'd': 'đ',
    'D': 'Đ',
    'c': 'ç',
    'C': 'Ç',
    'n': 'ñ',
    'N': 'Ñ',
    'ss': 'ß',
  };
  return {
    for (final MapEntry(key: base, value: letters) in groups.entries)
      for (final letter in letters.runes) String.fromCharCode(letter): base,
  };
}();

/// A GitHub repository named by URL — `owner/repo`, an https link, or an ssh remote.
///
/// Ported from the desktop's `core/repository_clone.dart` without the cloning it sits beside there.
class GitHubRepository {
  const GitHubRepository._(this.url, this.name);

  final String url, name;

  /// Null when [input] does not name a GitHub repository.
  ///
  /// ⚠️ Strict on purpose. The result is handed to a machine that will run `git clone` with it, so
  /// everything that could smuggle something else into that command — a userinfo, a port, a query,
  /// a fragment, a host that is not github.com — is refused rather than trimmed off and accepted.
  static GitHubRepository? parse(String input) {
    final text = input.trim();
    final ssh = text.startsWith('[email protected]:');
    String path;
    if (ssh) {
      path = text.substring('[email protected]:'.length);
    } else {
      final uri = Uri.tryParse(
        text.contains('://') ? text : 'https://github.com/$text',
      );
      if (uri == null ||
          uri.scheme != 'https' ||
          uri.host != 'github.com' ||
          uri.userInfo.isNotEmpty ||
          uri.hasPort ||
          uri.hasQuery ||
          uri.hasFragment) {
        return null;
      }
      path = uri.path.replaceFirst(RegExp(r'^/'), '');
    }
    path = path
        .replaceFirst(RegExp(r'/$'), '')
        .replaceFirst(RegExp(r'\.git$'), '');
    final parts = path.split('/');
    if (parts.length != 2 ||
        !RegExp(r'^[A-Za-z0-9][A-Za-z0-9-]{0,38}$').hasMatch(parts[0]) ||
        !RegExp(r'^[A-Za-z0-9_.-]{1,100}$').hasMatch(parts[1]) ||
        parts[1] == '.' ||
        parts[1] == '..') {
      return null;
    }
    return GitHubRepository._(
      ssh ? '[email protected]:$path.git' : 'https://github.com/$path.git',
      parts[1],
    );
  }
}