refactor(agents): improve writeAgents with file-level tracking by Paveltarno · Pull Request #228 · base44/cli

Paveltarno · 2026-02-11T09:29:46Z

Note

Description

This PR refactors writeAgents to track agent files by their actual path on disk rather than by a computed slug derived from the agent name. The result is idempotent pulls (unchanged files are skipped, preserving JSONC comments and formatting), correct handling of agents stored under custom filenames, and graceful fallback when a new remote agent's default filename is already claimed by an existing file.

Related Issue

None

Type of Change

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Documentation update
Refactoring (no functional changes)
Other (please describe):

Changes Made

src/core/resources/agent/config.ts: Removed toFileSlug helper; updated readAgentFile to return both parsed data and raw content; added AgentFileEntry interface and readAgentFiles / buildNameToEntryMap helpers; added findAvailablePath for _1/_2 suffix fallback on filename collisions; rewrote writeAgents to delete/update using actual disk paths, skip unchanged files, write in-place for custom-named files, and use InvalidInputError for duplicate name detection.
src/cli/commands/agents/pull.ts: Removed early-exit when remote list is empty; changed task messaging from "Writing"/"written" to "Syncing"/"synced"; added "All agents are already up to date" log when nothing changed.
tests/core/agents_write.spec.ts: New unit test suite covering write, delete, custom filename in-place update, skip-on-unchanged (comment preservation), changed-data overwrite, and filename collision lifecycle scenarios.
tests/cli/agents_pull.spec.ts: Extended CLI integration tests covering file creation on disk, skip-on-unchanged with comment preservation, naming clash handling, and in-place update scenarios.
Test fixtures: Added with-agents-for-pull and with-agents-naming-clash test fixtures.

Testing

I have tested these changes locally
I have added/updated tests as needed
All tests pass (npm test)

Checklist

My code follows the project's style guidelines
I have performed a self-review of my own code
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation (if applicable)
My changes generate no new warnings
I have updated docs/ (AGENTS.md) if I made architectural changes

Additional Notes

The previous implementation computed a filesystem slug from the agent name to locate files for deletion and updates. This broke when users stored agents under custom filenames (slug-based lookup found no file) and always rewrote every agent file on each pull (destroying JSONC comments). The new approach builds a name → file entry map from what is actually on disk, making all operations path-aware and idempotent.

_{🤖 Generated by Claude | 2026-02-23 09:42 UTC}

github-actions · 2026-02-11T09:30:17Z

🚀 Package Preview Available!

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.0.34-pr.228.21866ae

Prefer not to change any import paths? Install using npm alias so your code still imports base44:

npm i "base44@npm:@base44-preview/cli@0.0.34-pr.228.21866ae"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.0.34-pr.228.21866ae"
  }
}

📦 Preview Package: @base44-preview/cli@0.0.34-pr.228.21866ae
🔗 View this commit on GitHub

_{Preview published to npm registry — try new features instantly!}

Paveltarno · 2026-02-11T09:32:44Z

@claude run lint fix and typecheck fix

claude · 2026-02-11T09:33:00Z

Claude finished @Paveltarno's task in 32s —— View job

Unable to run lint fix and typecheck

I attempted to run the requested commands but I don't have permission to execute Bash commands in this repository. The following commands require approval:

bun install - Install dependencies
bun run lint:fix - Run Biome lint auto-fix
bun run typecheck - Run TypeScript type checking

What you can do

To allow me to run these commands, you'll need to update my permissions by adding --allowedTools=Bash to the GitHub Action configuration, or you can run these commands locally:

bun install
bun run lint:fix
bun run typecheck

Alternatively, you can approve the commands when I request them, or configure the repository to allow me to run Bash commands without approval.

claude · 2026-02-11T09:33:14Z

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

claude · 2026-02-11T09:36:04Z

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

Paveltarno · 2026-02-11T09:53:25Z

@claude lint fix

claude · 2026-02-11T09:53:38Z

Claude finished @Paveltarno's task in 54s —— View job

Lint fix completed

Install dependencies
Run lint fix
Commit and push any changes
Report results

Summary

Successfully ran bun run lint:fix which fixed 2 files with formatting improvements:

Changes made:

src/core/resources/agent/config.ts: Fixed function signature formatting
tests/core/agents_write.spec.ts: Fixed import ordering and object formatting

The changes have been committed and pushed to the agents-write-refactor branch.

--- | View commit

kfirstri · 2026-02-12T11:07:58Z

tests/cli/agents_pull.spec.ts

-    t.expectResult(result).toContain("Agent files written successfully");
+    t.expectResult(result).toContain("Agent files synced successfully");
    t.expectResult(result).toContain("Pulled 2 agents");
  });


can we create a fixture and also add a test that starts from the cli? and then check everything worked fine

@claude please (:

Claude finished @Paveltarno's task in 4m 59s —— View job

CLI fixture and integration tests added

Read existing test files and understand patterns

Create with-agents-for-pull fixture with existing agent file

Add CLI-level integration tests with file system assertions

Build and run tests — all 7 pass

Commit and push — 6b0fa71

What was added

New fixture tests/fixtures/with-agents-for-pull/:

base44/.app.jsonc, base44/config.jsonc — standard project structure

base44/agents/support_agent.jsonc — agent file with a // My support agent JSONC comment (used to detect rewrites)

Three new tests in tests/cli/agents_pull.spec.ts:

Test Fixture What it verifies

writes agent files to disk after pull basic File created at base44/agents/support_agent.jsonc with correct name, description, instructions

skips unchanged agents and preserves file content with-agents-for-pull "All agents are already up to date" message + JSONC comment still present (file not rewritten)

updates agent file in-place when remote data changes with-agents-for-pull Same file path preserved, content updated to new description/instructions

View commit

@claude, thank you, just add another test for when there's a file naming clash

Claude finished @Paveltarno's task in 4m 46s —— View job

Naming clash test added

Read existing tests and agent config to understand naming clash scenario

Fix writeAgents to detect file naming clashes

Create with-agents-naming-clash fixture

Add CLI-level test for file naming clash

Run tests — all 177 pass

Commit and push — 7d1f297

What was added

New fixture tests/fixtures/with-agents-naming-clash/:

base44/agents/custom_name.jsonc — agent stored with a custom filename but name: "support_agent"

Bug fix in src/core/resources/agent/config.ts (writeAgents):
Before this PR, if a remote returned both support_agent (written to the existing custom_name.jsonc) and a new agent named custom_name (whose default path would also be custom_name.jsonc), the new agent would silently overwrite the first. Now it throws:

Cannot write agent "custom_name": file "…/custom_name.jsonc" is already used by another agent

New test in tests/cli/agents_pull.spec.ts:

fails when a new remote agent's default filename clashes with an existing custom-named file

Uses the with-agents-naming-clash fixture, mocks remote returning both agents, asserts the command fails and the output contains "custom_name".

View commit |

tests/core/agents_write.spec.ts

kfirstri

🚀

kfirstri · 2026-02-22T12:04:31Z

@Paveltarno lets rebase / fix this PR and merge 🙏

…ip-unchanged Refactor writeAgents to track files by content name rather than filename, enabling correct updates when filenames don't match agent names. Skip writing unchanged data to preserve comments and formatting. Add duplicate name validation in write path for consistency with readAllAgents. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

The early return skipped writeAgents() when remote had 0 agents, preventing deletion of stale local files. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-authored-by: paveltarno <Paveltarno@users.noreply.github.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Add `with-agents-for-pull` fixture with a JSONC-commented agent file - Add tests verifying agent files are written to disk with correct content - Add test verifying unchanged agents are skipped (JSONC comment preserved) - Add test verifying changed agents are updated in-place at existing path Co-authored-by: paveltarno <Paveltarno@users.noreply.github.com>

…sion When an existing agent file uses a custom filename (e.g. custom_name.jsonc for an agent named "support_agent"), and a new remote agent arrives whose default filename matches that custom file, writeAgents now throws an error instead of silently overwriting the first agent's file. - Detects clash by tracking claimed file paths before writing new agents - Adds with-agents-naming-clash fixture (custom_name.jsonc with name "support_agent") - Adds CLI test asserting the command fails and mentions the clashing name Co-authored-by: paveltarno <Paveltarno@users.noreply.github.com>

When a new agent's default filename is already taken by a different agent's custom-named file, use a suffixed path (e.g. greeter_1.jsonc) instead of throwing. Aligns with how connectors handle duplicates (InvalidInputError with hints via shared buildNameToEntryMap helper). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Paveltarno force-pushed the agents-write-refactor branch from 423bc4e to 57ac95b Compare February 11, 2026 09:31

base44 deleted a comment from claude bot Feb 11, 2026

Paveltarno mentioned this pull request Feb 11, 2026

ci: allow Claude bot to run bun + gh commands #229

Merged

kfirstri added this to CLI Development Feb 12, 2026

github-project-automation bot moved this to Backlog in CLI Development Feb 12, 2026

kfirstri reviewed Feb 12, 2026

View reviewed changes

tests/core/agents_write.spec.ts Show resolved Hide resolved

kfirstri previously approved these changes Feb 12, 2026

View reviewed changes

github-project-automation bot moved this from Backlog to In review in CLI Development Feb 12, 2026

Paveltarno and others added 4 commits February 23, 2026 13:59

fix(agents): remove early return in pull command when remote is empty

d992c00

The early return skipped writeAgents() when remote had 0 agents, preventing deletion of stale local files. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

style: apply biome lint fixes

e74910b

Co-authored-by: paveltarno <Paveltarno@users.noreply.github.com>

fix(tests): update agents pull test expectations to match new messages

d7d5680

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Paveltarno dismissed kfirstri’s stale review via d7d5680 February 23, 2026 12:15

Paveltarno force-pushed the agents-write-refactor branch from c568c5d to d7d5680 Compare February 23, 2026 12:15

Paveltarno and others added 5 commits February 23, 2026 14:19

fix: remove unused toFileSlug function

8b02c4e

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

style: fix trailing commas in agents write tests

fee405f

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Paveltarno merged commit 35e37af into main Feb 23, 2026
9 checks passed

Paveltarno deleted the agents-write-refactor branch February 23, 2026 13:36

github-project-automation bot moved this from In review to Done in CLI Development Feb 23, 2026

Test	Fixture	What it verifies
`writes agent files to disk after pull`	`basic`	File created at `base44/agents/support_agent.jsonc` with correct `name`, `description`, `instructions`
`skips unchanged agents and preserves file content`	`with-agents-for-pull`	"All agents are already up to date" message + JSONC comment still present (file not rewritten)
`updates agent file in-place when remote data changes`	`with-agents-for-pull`	Same file path preserved, content updated to new description/instructions
View commit

Comments

Conversation

Paveltarno commented Feb 11, 2026 • edited by claude bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related Issue

Type of Change

Changes Made

Testing

Checklist

Additional Notes

Uh oh!

github-actions bot commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 Package Preview Available!

Uh oh!

Paveltarno commented Feb 11, 2026

Uh oh!

claude bot commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Unable to run lint fix and typecheck

What you can do

Uh oh!

claude bot commented Feb 11, 2026

Code review

Uh oh!

claude bot commented Feb 11, 2026

Code review

Uh oh!

Paveltarno commented Feb 11, 2026

Uh oh!

claude bot commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Lint fix completed

Summary

Uh oh!

kfirstri Feb 12, 2026

Choose a reason for hiding this comment

Uh oh!

Paveltarno Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

claude bot Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

CLI fixture and integration tests added

What was added

Uh oh!

Paveltarno Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

claude bot Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Naming clash test added

What was added

Uh oh!

Uh oh!

kfirstri left a comment

Choose a reason for hiding this comment

Uh oh!

kfirstri commented Feb 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Paveltarno commented Feb 11, 2026 •

edited by claude bot

Loading

github-actions bot commented Feb 11, 2026 •

edited

Loading

claude bot commented Feb 11, 2026 •

edited

Loading

claude bot commented Feb 11, 2026 •

edited

Loading

claude bot Feb 23, 2026 •

edited

Loading

claude bot Feb 23, 2026 •

edited

Loading