@teambit/ci 1.0.642 → 1.0.644

package/sync/agents-sync-section.md

@@ -0,0 +1,132 @@
+<!-- bit-ci-sync:start (written by `bit ci sync --init`; a re-run leaves this block as it is) -->
+
+## Bit ↔ Git sync: this repository mirrors `{{scope}}`
+
+`bit ci sync` keeps this repository and the bit.cloud scope `{{scope}}` equal in both directions. **The rules in this section override the generic Bit guidance after it.**
+
+### The model
+
+1. **One repository mirrors one scope.** Components from other scopes arrive as package dependencies, never as source.
+2. **`{{branch}}` equals the scope's main.** The workflows own it. Never push to `{{branch}}` by hand.
+3. **Each lane is a branch plus a pull request.** The sync keeps them equal in both directions. By default, the branch has the lane's name. A lane name has no `/`, so the default mapping ignores a branch such as `feature/x`. The `branchPrefix` and `branches` keys of the `teambit.git/ci` sync config in `workspace.jsonc` can map a lane to a different branch name, such as `lane/x`. Read them before you name a branch.
+4. **Merging the pull request is the release.** `bit-release` merges the lane into the scope, exports new versions, commits the new `.bitmap` to `{{branch}}` and archives the lane. A lane with components of other scopes stays open until each of those scopes releases its slice.
+5. **The workflows do the work.** You change code, and then you either push a branch or export a lane.
+
+### Rules that override generic Bit guidance
+
+- **Review happens on the GitHub pull request.** Do **not** submit a bit.cloud change request, even if other instructions say "always submit a change request". The sync opens the PR. Merging the PR is the release. A second review surface splits the reviewers and races the release.
+- **One change, one scope.** Keep a lane inside the scope it is exported to. If the change also needs another scope (for example, a caller must pass a new argument), stop. Make the change backward compatible in this scope, and tell the user which follow-up change the other scope's repository needs. Cross-scope lanes are a preview (see below).
+- **Never push to `{{branch}}`.** The workflows own it.
+
+### Make a change: pick a path
+
+| You are…                                                        | Path          | What you do                                                           | What appears                                                                                                                               |
+| --------------------------------------------------------------- | ------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| In this repository (Copilot, an IDE, a plain git user)          | **Git-first** | branch → edit → `bit validate` → commit → push → open a PR            | With the optional `bit-adopt-pr` workflow, the PR becomes a lane, and every push snaps onto it. Without it, the sync ignores the branch.   |
+| In any other Bit workspace (Claude Code with the Bit Cloud MCP) | **Bit-first** | `bit lane create` → edit → `bit validate` → `bit snap` → `bit export` | A branch and a PR named after the lane appear in this repository: within a minute with the scope webhook, else at the next scheduled sync. |
+
+Both paths end with the same PR and the same release.
+
+#### Git-first (in this repository)
+
+This path needs the `bit-adopt-pr` workflow in `.github/workflows/`. On each push to a PR, it runs `bit ci pr --keep-lane`: this creates and exports a lane with the branch's name, and pushes the lane pointer back to the branch. `bit ci sync --init` does not write this workflow. Example: https://github.com/teambit/acme-modular-store/blob/main/.github/workflows/bit-adopt-pr.yml. Without it, a branch that has no lane stays out of the sync: use the Bit-first path.
+
+```bash
+git switch -c add-gift-wrap                 # the lane gets the branch's name, so no "/"
+bit install                                  # once per clone
+# edit the components; .bitmap says where each one lives
+bit validate                                 # lint + types + tests; never use tsc directly
+git add -A && git commit -m "<message>"
+git push -u origin add-gift-wrap
+gh pr create --fill
+```
+
+Commit `.bitmap` together with your source changes. Never edit `.bitmap` by hand. After the PR merges, run `git switch {{branch-sh}} && git pull` before you start the next change.
+
+#### Bit-first (from another Bit workspace)
+
+1. Find components with the Bit Cloud MCP: `read_scope` / `search_components` for the owner, `read_components` for APIs, and `read_file` for source. Don't guess IDs. Also check who calls the component, so you know whether your change stays inside one scope.
+2. Run:
+
+```bash
+bit init --default-scope {{scope}}           # or reuse an existing workspace
+bit import {{scope}}/<name> [...]            # every component you will change, plus the chain up to its consumers
+bit lane create <lane-name>
+# edit
+bit validate
+bit snap -m "<message>"
+bit export
+```
+
+3. Watch it arrive: `gh pr list -R {{repo}} --head <lane-name>`. Then tell the user the PR link. Don't submit a bit.cloud change request.
+
+Headless or CI agents can call the Bit Cloud MCP with a bit.cloud token, without the OAuth step:
+
+```json
+{
+  "mcpServers": {
+    "bit-cloud": {
+      "type": "http",
+      "url": "https://mcp.bit.cloud/mcp",
+      "headers": { "Authorization": "Bearer ${BIT_CLOUD_TOKEN}" }
+    }
+  }
+}
+```
+
+### Read a sync PR
+
+- The PR body lists the mirrored components and the foreign ones (other scopes, "not mirrored").
+- The bot's **run summary** comment lists the components that the sync last snapped onto the lane from this branch, with the branch and lane heads. A run that exports nothing does not change it.
+- The run log says what each run did: `import-lane`, `export-branch`, `merge-diverged`, `adopt-branch`, `noop (converged)`. Runs: `gh run list --workflow bit-sync` and `gh run view <id> --log`.
+- `Lane sync: <scope>/<lane>` PRs are lanes. `Bit sync: update to latest main scope versions` brings `{{branch}}` up to the scope. Merging that one releases nothing. Its branch is `bit-sync/main`, or the `mainSyncBranch` of the sync config. With `mainSync: "direct-push"` there is no such PR: the sync commits to `{{branch}}` itself.
+
+### Fix a halt (`bit-sync-conflict` label)
+
+The lane and the branch changed the same lines. The lane stays paused while the label is on the PR. The bot's comment on the PR names the components and gives these steps:
+
+```bash
+git fetch origin && git checkout '<branch>'
+git merge --ff-only 'origin/<branch>'         # stops if your local copy has commits that are not on origin: keep them, or reset to origin
+bit install
+bit lane import '<host-scope>/<lane>'         # fetches the lane. If .bitmap is on main, it also switches to the lane
+bit checkout head --manual --workspace-only   # merges the lane's head into the files; conflicts appear as conflict markers
+# resolve every conflicted file. When the intent is unclear, ask the user which side wins. Don't guess.
+bit validate
+git add -A && git commit -m "fix: resolve sync conflict"
+git push origin '<branch>'
+gh pr edit <pr> --remove-label bit-sync-conflict
+gh workflow run bit-sync -f lane=<host-scope>/<lane>
+```
+
+`--workspace-only` keeps the components of other scopes out of this repository. The next run adds the lane's new components of `{{scope}}`. Its log shows `merge-diverged` or `export-branch`, then a later run shows `noop (converged)`. Never resolve by force-pushing over the bot's commits. Never delete the lane to "start fresh".
+
+### Change several scopes at once (preview)
+
+Prefer one lane per scope: one change, one repository, one PR.
+
+A lane _can_ carry components from several scopes. Each scope's repository then mirrors only its own slice, consumes the other scopes' lane versions as packages, and releases its slice when its PR merges. The lane stays open until the last slice is released. Until automatic fan-out ships, only the repository of the lane's host scope hears about the lane. Start the others by hand:
+
+```bash
+gh workflow run bit-sync -R <org>/<repo> -f lane=<host-scope>/<lane-name>
+```
+
+### Connect another scope to its own repository
+
+```bash
+gh repo create <org>/<repo> --private --clone && cd <repo>
+bit init --default-scope <owner>.<scope> --skip-interactive
+bit import "<owner>.<scope>/**"
+bit ci sync --init                            # writes the workflows, the sync config and this AGENTS.md section
+```
+
+Then follow the steps `bit ci sync --init` prints. Some of them need a repository or organization admin. Guide: https://bit.cloud/teambit/git/guides/connect-scope-to-repository
+
+### Never
+
+- Push to `{{branch}}`, or merge the main-sync PR and lane PRs out of order to "fix" history.
+- Run `bit build`, `tsc`, `npm install` or `pnpm install` here. Use `bit validate` and `bit install`.
+- Export a lane from another workspace while a Git-first PR is open for the same change. Pick one path.
+- Remove a `bit-sync-conflict` label without resolving the conflict.
+
+<!-- bit-ci-sync:end -->

package/sync/init-scaffold.ts

@@ -3,6 +3,7 @@ import chalk from 'chalk';
 import { formatHint, formatItem, formatTitle, formatWarningSummary, joinSections, successSymbol } from '@teambit/cli';
 import path from 'path';
 import { parseGitHubRepo, isGitHubRemote, gitHubApiUrl, remoteHost } from './github-client';
+import { AGENTS_MD_RELATIVE_PATH } from './agents-md';
 
 /**
  * `bit ci sync --init` — pure scaffolding logic, unit-testable without a live workspace/git checkout.
@@ -272,7 +273,10 @@ export function renderBitReleaseWorkflow(defaultBranch: string, wsDir?: string):
 export interface ScaffoldFileOutcome {
   /** relative to the workspace root, e.g. `.github/workflows/bit-sync.yml` */
   relativePath: string;
-  status: 'written' | 'skipped';
+  /** `updated`: the file existed and `--init` added to it (the AGENTS.md sync section) */
+  status: 'written' | 'updated' | 'skipped';
+  /** what `--init` did, when the status alone does not say it */
+  note?: string;
 }
 
 // Never overwrites an existing file — `--init` must be safe to re-run after hand-edits.
@@ -344,8 +348,19 @@ const SETUP_GUIDE_URL = 'https://github.com/teambit/acme-modular-store#set-it-up
 const FILE_PURPOSE: Record<string, string> = {
   [WORKFLOW_RELATIVE_PATHS.sync]: 'syncs lanes and branches: on export, on push, and every 30 minutes',
   [WORKFLOW_RELATIVE_PATHS.release]: 'releases the scope when a pull request merges',
+  [AGENTS_MD_RELATIVE_PATH]: 'tells coding agents how the sync works in this repository',
 };
 
+/** The note the report shows next to a file. */
+function fileNote(file: ScaffoldFileOutcome): string {
+  if (file.note) return file.note;
+  if (file.status === 'written') return FILE_PURPOSE[file.relativePath] ?? '';
+  if (file.status === 'updated') return 'added the sync rules at the top';
+  return file.relativePath === AGENTS_MD_RELATIVE_PATH
+    ? 'already has the sync rules, left unchanged'
+    : 'already exists, left unchanged';
+}
+
 export interface InitReportInput {
   /** the workspace's default scope, the one this repository mirrors */
   scopeId?: string;
@@ -368,7 +383,7 @@ export interface InitReportInput {
   repoHasCommits?: boolean;
   /** false when the workspace is not in a git repository yet: step 1 then starts with `git init` */
   inGitRepo?: boolean;
-  /** scaffolded workflow files, with the path to show (relative to where the user stands) */
+  /** scaffolded files (the workflows, AGENTS.md), with the path to show (relative to where the user stands) */
   files: Array<ScaffoldFileOutcome & { displayPath: string }>;
   /** workspace.jsonc, as seen from where the user stands */
   configDisplayPath?: string;
@@ -490,8 +505,8 @@ export function renderInitReport(input: InitReportInput): string {
     const why = input.originUrl ? "the remote didn't name its default branch" : 'no remote names the default branch';
     header.push(
       formatWarningSummary(
-        `${why}, so the workflows use "${defaultBranch}". If that's wrong,\n` +
-          `  edit the branch filters in both workflow files.`
+        `${why}, so the workflows and AGENTS.md use "${defaultBranch}". If that's wrong,\n` +
+          `  edit the branch filters in both workflow files and the branch in the AGENTS.md sync section.`
       )
     );
   }
@@ -507,12 +522,7 @@ export function renderInitReport(input: InitReportInput): string {
   const width = Math.max(...input.files.map((f) => f.displayPath.length), configDisplayPath.length) + 2;
   const fileItem = (displayPath: string, note: string) => formatItem(`${displayPath.padEnd(width)}${formatHint(note)}`);
   const files = [
-    ...input.files.map((file) =>
-      fileItem(
-        file.displayPath,
-        file.status === 'written' ? (FILE_PURPOSE[file.relativePath] ?? '') : 'already exists, left unchanged'
-      )
-    ),
+    ...input.files.map((file) => fileItem(file.displayPath, fileNote(file))),
     fileItem(
       configDisplayPath,
       input.configAdded ? 'added "teambit.git/ci": { "sync": {} }' : 'already configures sync, left unchanged'

package/sync/lane-sync-executor.spec.ts

@@ -350,8 +350,13 @@ describe('haltCommentBody', () => {
       branch: LANE_NAME,
       laneId: `acme.shop/${LANE_NAME}`,
     });
-    expect(body).to.include(`git fetch origin && git checkout '${LANE_NAME}'`);
+    expect(body).to.include(
+      `git fetch origin && git checkout '${LANE_NAME}' && git merge --ff-only 'origin/${LANE_NAME}'`
+    );
     expect(body).to.include(`bit lane import 'acme.shop/${LANE_NAME}'`);
+    // On a branch whose .bitmap is already on the lane, `bit lane import` only fetches: the merge is this step.
+    // --workspace-only: no component of another scope lands here. The next run adds new ones of this scope.
+    expect(body).to.include('bit checkout head --manual --workspace-only');
     expect(body).to.include(`git push origin '${LANE_NAME}'`);
     // the reason is prose, not a command, and the runbook still reads as one
     expect(body).to.include('merge conflicts in: acme.shop/comp1');

package/sync/lane-sync-executor.ts

@@ -1932,8 +1932,9 @@ export function haltCommentBody({
   const resolution =
     note ??
     `To resolve locally:
-  git fetch origin && git checkout ${shellQuote(branch)}
+  git fetch origin && git checkout ${shellQuote(branch)} && git merge --ff-only ${shellQuote(`origin/${branch}`)}
   bit lane import ${shellQuote(laneId)}
+  bit checkout head --manual --workspace-only   # merges the lane's head into the files; conflicts get conflict markers
   # resolve conflicts, commit the result, then:
   git push origin ${shellQuote(branch)}`;
   return `bit-git-sync could not reconcile this branch automatically: ${reason}

package/sync/sync-orchestrator.ts

@@ -24,6 +24,7 @@ import { MainSyncExecutor } from './main-sync-executor';
 import { selectGitHostProvider } from './git-host-provider';
 import { gitRepoRoot, isNonContentPath, listRemoteBranches } from './git-ops';
 import { chooseInitDefaultBranch, deriveOwnerRepo, renderInitReport, scaffoldWorkflowFiles } from './init-scaffold';
+import { UNKNOWN_REPO, scaffoldAgentsMd } from './agents-md';
 
 /**
  * Refuse a `--dry-run` whose plan would be computed by force-checking-out branches over uncommitted
@@ -209,8 +210,9 @@ export class SyncOrchestrator {
 
   /**
    * `bit ci sync --init` — one-command onboarding: scaffolds the two workflow files, adds the sync
-   * config block to workspace.jsonc if missing, and returns the report of the steps left. Safe to
-   * re-run: existing files are skipped, an existing config block is left alone; it never reconciles.
+   * config block to workspace.jsonc if missing, puts the sync rules for coding agents into AGENTS.md,
+   * and returns the report of the steps left. Safe to re-run: existing files are skipped, an existing
+   * config block or AGENTS.md sync section is left alone; it never reconciles.
    */
   private async syncInit(): Promise<string> {
     const remoteUrl = await git.remote(['get-url', 'origin']).catch(() => undefined);
@@ -249,6 +251,15 @@ export class SyncOrchestrator {
       return fromCwd && !path.isAbsolute(fromCwd) ? fromCwd : abs;
     };
     const configAdded = await this.ensureSyncConfigBlock();
+    // AGENTS.md belongs to the workspace, where agents run bit commands.
+    const ownerRepo = deriveOwnerRepo(origin);
+    const agentsOutcome = scaffoldAgentsMd(this.deps.workspace.path, {
+      scope: this.deps.workspace.defaultScope ?? '<owner>.<scope>',
+      repo: ownerRepo
+        ? `${ownerRepo.host === 'github.com' ? '' : `${ownerRepo.host}/`}${ownerRepo.owner}/${ownerRepo.repo}`
+        : UNKNOWN_REPO,
+      defaultBranch,
+    });
     // No commit yet: the first commit must take the whole workspace, not only the files --init wrote.
     const repoHasCommits = await git
       .raw(['rev-parse', '--verify', '--quiet', 'HEAD'])
@@ -260,6 +271,7 @@ export class SyncOrchestrator {
     const handled = [
       ...fileOutcomes.map((outcome) => path.join(scaffoldRoot, outcome.relativePath)),
       path.join(this.deps.workspace.path, 'workspace.jsonc'),
+      path.join(this.deps.workspace.path, agentsOutcome.relativePath),
     ];
     const toStage: string[] = [];
     const ignored: string[] = [];
@@ -291,7 +303,7 @@ export class SyncOrchestrator {
     // Returned, not logged: the command prints what `report()` returns.
     return renderInitReport({
       scopeId: this.deps.workspace.defaultScope,
-      ownerRepo: deriveOwnerRepo(origin),
+      ownerRepo,
       originUrl: origin,
       defaultBranch,
       defaultBranchGuessed: !detectedBranch,
@@ -299,10 +311,13 @@ export class SyncOrchestrator {
       repoRootFromCwd: path.relative(process.cwd(), scaffoldRoot) || '.',
       repoHasCommits,
       inGitRepo: Boolean(repoRoot),
-      files: fileOutcomes.map((outcome) => ({
-        ...outcome,
-        displayPath: displayPath(path.join(scaffoldRoot, outcome.relativePath)),
-      })),
+      files: [
+        ...fileOutcomes.map((outcome) => ({
+          ...outcome,
+          displayPath: displayPath(path.join(scaffoldRoot, outcome.relativePath)),
+        })),
+        { ...agentsOutcome, displayPath: displayPath(path.join(this.deps.workspace.path, agentsOutcome.relativePath)) },
+      ],
       configDisplayPath: displayPath(path.join(this.deps.workspace.path, 'workspace.jsonc')),
       configAdded,
       ...(repoRoot ? { toStage, ignored } : {}),