feat(agents): implement blit agents sync --check drift detection

[vancura]

Replace the agents stub with a real sync --check command. Reads .blit/manifest.json, SHA-256s every kit-owned and shared file on disk, and reports any that differ from the seeded hash or are missing. Exits non-zero on drift, making it safe for CI use.

Also integrates the drift check into blit doctor (appended as the last health check, no change to doctor's exit code) and updates the help text in cli.ts to remove the "coming soon" note.

Two new end-to-end tests cover the clean (exit 0) and drifted (exit 1, file named in output) cases.

Overview

This pull request implements the blit agents sync --check command for drift detection, replacing the previous stub with a real manifest-driven implementation. The command reads .blit/manifest.json, computes SHA-256 hashes for kit-owned and shared files on disk, reports missing or changed files, and is suitable for CI because it sets a non-zero exit code when drift is detected. The drift check is also integrated into blit doctor as the final health check (no change to doctor's overall exit code).

Changes

Core Implementation (packages/kit/src/commands/agents.ts)

• Replaced the stub with a manifest-driven drift checker.
• Added types for manifest entries and a SHA-256 helper.
• Implemented checkSyncDrift(root: string, out: (line: string) => void): number which:
  • Reads and validates .blit/manifest.json.
  • Checks only kit-owned and shared entries.
  • Safely resolves manifest paths (skips absolute/escaping paths).
  • Computes on-disk SHA-256, reports missing files and mismatches, returns 0 when clean or a positive drift count on drift (or 1 on manifest read/format errors).
• Updated runAgents() to:
  • Locate the project root and run the drift check for sync --check.
  • Set process.exitCode = 1 when drift is detected.
  • Keep non---check sync and add behavior as informational/coming-soon messages.

CLI Updates (packages/kit/src/cli.ts)

• Updated help text for the agents command to "Manage AI-assistant files (sync, add)", removing the "coming soon" note.

Doctor Integration (packages/kit/src/commands/doctor.ts)

• Added a "Sync drift" check that invokes checkSyncDrift() and prints results as the last doctor health check without changing the doctor's exit behavior.

Tests (packages/create-blit-tech/test/scaffold.test.mjs)

• Added end-to-end coverage for blit agents sync --check:
  • One test asserts exit code 0 when no drift is present.
  • Another test scaffolds a project, mutates a kit-managed Claude rule file, and asserts non-zero exit (and that the drifted filename is reported).

Exit Behavior

• Command exits 0 when no drift is detected; exits non-zero when drift or manifest errors are detected, making it suitable for CI integration.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 346ddf0e-e6bb-459c-b3d4-a2a89df221b5

📥 Commits

Reviewing files that changed from the base of the PR and between 2c1499d and 6440ce5.

📒 Files selected for processing (1)

• packages/kit/src/commands/agents.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/kit/src/commands/agents.ts

---

Walkthrough

Adds a manifest-driven SHA-256 drift checker (checkSyncDrift), wires it into blit agents sync --check and the doctor command, updates CLI help, and adds end-to-end tests for clean and drifted states.

Changes

Sync Drift Detection Feature

Layer / File(s)	Summary
Manifest contract and drift detection packages/kit/src/commands/agents.ts	Introduces manifest interfaces and SHA-256 helper; implements checkSyncDrift(root, out) to read .blit/manifest.json, filter kit-managed entries, compute on-disk SHA-256, report statuses, and return drift or error codes.
Sync check command routing and CLI help packages/kit/src/cli.ts, packages/kit/src/commands/agents.ts	Updates CLI help to describe agents as "Manage AI-assistant files (sync, add)". Adds sync --check routing in runAgents() to locate project root, invoke checkSyncDrift(), and set exit codes for missing projects or detected drift; non-check subcommands remain placeholders.
Doctor sync drift diagnostic packages/kit/src/commands/doctor.ts	Imports checkSyncDrift and adds a "Sync drift" phase in runDoctor() that invokes checkSyncDrift(root, out) to display drift diagnostics.
End-to-end tests for sync --check packages/create-blit-tech/test/scaffold.test.mjs	Extends test imports to include writeFileSync, adds blitCli pointing to the CLI entrypoint, and appends tests: one validates no-drift success; another modifies a kit-managed file and asserts sync --check exits non-zero and reports the drifted filename.

Sequence Diagram

sequenceDiagram
  participant User
  participant CLI
  participant runAgents
  participant checkSyncDrift
  participant FileSystem
  participant Process
  User->>CLI: blit agents sync --check
  CLI->>runAgents: sync --check
  runAgents->>runAgents: locate project root
  runAgents->>checkSyncDrift: checkSyncDrift(root, out)
  checkSyncDrift->>FileSystem: read .blit/manifest.json
  checkSyncDrift->>FileSystem: read tracked files
  checkSyncDrift->>checkSyncDrift: compare SHA-256 hashes
  alt Drift detected
    checkSyncDrift->>User: report drifted files
    runAgents->>Process: set exitCode = 1
  else No drift
    checkSyncDrift->>User: report "up to date"
  end

Loading

Possibly related PRs

• vancura/create-blit-tech#6: Modifies Claude rule/agent-skill files that the drift checker targets.
• vancura/create-blit-tech#10: Seeds .blit/manifest.json entries used by the drift checker.
• vancura/create-blit-tech#12: Changes how scaffolded Claude files are generated/classified and recorded in the manifest, affecting drift detection.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely describes the main feature addition: implementing the blit agents sync --check drift detection command.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agents-sync

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[vancura]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/kit/src/commands/agents.ts`:
- Around line 61-71: The code assumes manifest.files is an array and calls
manifest.files.filter; validate the manifest shape after parsing by checking
that manifest && Array.isArray(manifest.files) before using it (the variable
manifest and the subsequent tracked assignment), and if the check fails call
out(ui.error(...)) with a clear message about an invalid/damaged manifest and
return 1 so the command exits gracefully; update the logic that defines tracked
to only run when the check passes (or set tracked = [] when absent) and ensure
downstream code that uses missing/ tracked behaves correctly.
- Around line 75-77: The loop over tracked entries uses join(root, entry.path)
which allows absolute paths or “..” segments to escape the project root; update
the code around join(root, entry.path) (the absPath calculation) to first reject
or normalize unsafe entry.path values: if path.isAbsolute(entry.path) or
path.normalize(entry.path).startsWith('..' + path.sep) then skip or error,
otherwise compute const absPath = path.resolve(root, entry.path) and verify
absPath === root || absPath.startsWith(root + path.sep) before using it; this
ensures manifest paths cannot point outside the repo and prevents hashing
arbitrary files.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 601667b7-395f-4c80-8b4d-57ecfbaa7191

📥 Commits

Reviewing files that changed from the base of the PR and between 71e0714 and 2c1499d.

📒 Files selected for processing (4)

• packages/create-blit-tech/test/scaffold.test.mjs
• packages/kit/src/cli.ts
• packages/kit/src/commands/agents.ts
• packages/kit/src/commands/doctor.ts

[vancura]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[vancura]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.