fix(cli): backfill command

[calvinbrewer]

Summary by CodeRabbit

• Bug Fixes
  • Fixed schema column metadata resolution in the backfill command.
  • Configuration errors now display clearer, author-controlled messages for easier troubleshooting.
  • Improved error diagnostics to distinguish configuration issues from unexpected failures.

[changeset-bot]

🦋 Changeset detected

Latest commit: 439c63e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
stash	Patch
@cipherstash/e2e	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4c5092c2-86d6-4296-ab9c-feb34f466860

📥 Commits

Reviewing files that changed from the base of the PR and between 2a669d9 and 439c63e.

📒 Files selected for processing (2)

• .changeset/fix-backfill-cli-wrapper.md
• packages/cli/src/commands/encrypt/backfill.ts

---

📝 Walkthrough

Walkthrough

The backfill CLI command is enhanced with explicit schema column resolution, improved cast_as validation, and refined error categorization that distinguishes configuration errors from transient failures.

Changes

Backfill CLI Schema Resolution & Error Handling

Layer / File(s)	Summary
Type & Error Infrastructure packages/cli/src/commands/encrypt/backfill.ts (imports & definition)	Added imports for ColumnSchema, castAsEnum, toEqlCastAs from @cipherstash/stack/schema; introduced BackfillConfigError class for author-controlled configuration messages.
Schema Resolution Helpers packages/cli/src/commands/encrypt/backfill.ts (helpers)	Added resolveSchemaColumnKey(...) to resolve the schema column key with fallback logic (explicit flag, encrypted-column key, plaintext-column key) and throws BackfillConfigError if unresolvable. Added translateCastAs(...) to validate SDK cast_as values and map them to EQL castAs, throwing BackfillConfigError on invalid schema types.
Coercer & Manifest Builders packages/cli/src/commands/encrypt/backfill.ts (functions)	Simplified buildPlaintextCoercer to accept only `castAs: string
Main Command Logic packages/cli/src/commands/encrypt/backfill.ts (try block)	Updated backfill command to build columns map from schema, resolve schemaColumnKey via the new helper, select matching ColumnSchema, and pass it into manifest entry creation.
Error Categorization packages/cli/src/commands/encrypt/backfill.ts (catch block)	Enhanced error handling to log BackfillConfigError messages directly (author-controlled), while preserving generic error logging for non-config failures.
Release Documentation .changeset/fix-backfill-cli-wrapper.md	New Changesets patch entry for "stash" documenting schema column metadata resolution and improved error messaging.

Sequence Diagram

sequenceDiagram
    participant CLI as CLI Command
    participant Schema as Schema Module
    participant Helpers as Resolution Helpers
    participant Manifest as Manifest Builder
    participant Error as Error Handler

    CLI->>Schema: Extract columns map
    Schema-->>CLI: columns metadata
    CLI->>Helpers: resolveSchemaColumnKey()
    alt Schema key found
        Helpers-->>CLI: schemaColumnKey
    else Schema key missing
        Helpers-->>Error: BackfillConfigError
        Error-->>CLI: Log author message
    end
    CLI->>Helpers: translateCastAs(column.cast_as)
    alt Valid cast_as
        Helpers-->>CLI: EQL castAs
    else Invalid cast_as
        Helpers-->>Error: BackfillConfigError
        Error-->>CLI: Log author message
    end
    CLI->>Manifest: buildManifestEntry(ColumnSchema)
    Manifest-->>CLI: manifest entry
    Note over Error: Non-config errors<br/>suppress sensitive data

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Suggested reviewers

• auxesis

Poem

🐰 A schema resolved, so clean and bright,
Errors now speak with author's might,
No secrets slip from sundry logs,
The backfill hops through column bogs,
Config and fate, now split aright! ✨

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	The title 'fix(cli): backfill command' is vague and overly broad. While it mentions the backfill command, it lacks specificity about what aspect of the backfill command was fixed (schema resolution, error handling, manifest generation, etc.).	Consider a more specific title that describes the main fix, such as 'fix(cli): backfill schema column key resolution and error handling' or similar to better convey what was improved.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
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 fix-backfill-command

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

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