@inf-minds/carto

Carto knowledge-library integration for MindKit, including wrapper-backed tools, a carto_cli escape hatch, route-contract coverage, and a live backend smoke suite.

Supported Surface

Wrapper-backed tools:

• search_knowledge -> item search
• browse_folders -> folder tree, folder list
• get_item -> item get
• create_folder -> folder create
• move_folder -> folder move
• delete_folder -> folder delete
• list_items -> item list
• get_item_by_uri -> item get-by-uri
• get_item_segments -> item segments
• upload_item -> item upload
• delete_item -> item delete
• list_share_links -> share-link list
• create_share_link -> share-link create
• delete_share_link -> share-link delete

Supported through carto_cli only:

• folder get
• folder update
• folder restructure
• folder create-tree
• item create
• item update
• item update content
• item assign
• share-link analytics

Live Smoke Suite

The live smoke suite is opt-in and targets the real backend routes implemented under:

• /Users/pureicis/dev/carto/backend_v1/src/routes/libraries/folders.ts
• /Users/pureicis/dev/carto/backend_v1/src/routes/libraries/folder-reorganization.ts
• /Users/pureicis/dev/carto/backend_v1/src/routes/libraries/knowledge.ts
• /Users/pureicis/dev/carto/backend_v1/src/routes/auth/cli.ts

It exercises the package through its real tool surface and verifies:

• read connectivity via folder browsing
• folder create, update, move, create-tree, restructure, and cleanup flows
• knowledge item create, get, list, get-by-uri, segments, metadata update, and content update flows
• item-to-folder assignment and reassignment
• share-link create, list, analytics, and delete flows
• cleanup of created smoke-test artifacts

Optional live upload verification is available separately for storage-enabled environments.

Required Environment

Set these before running the live suite:

export CARTO_LIVE_SMOKE=1
export CARTO_API_BASE_URL=http://localhost:3000
export CARTO_AUTH_TOKEN=<bearer-token>
export CARTO_LIBRARY_ID=<writable-library-uuid>

Optional:

export CARTO_PARENT_FOLDER_ID=<sandbox-parent-folder-uuid>
export CARTO_TEST_TIMEOUT_MS=45000
export CARTO_TEST_RUN_ID=my-debug-run
export CARTO_KEEP_ARTIFACTS=1
export CARTO_LIVE_SMOKE_UPLOAD=1

Running

pnpm --filter @inf-minds/carto test:live

Without CARTO_LIVE_SMOKE=1, the live suite skips cleanly and performs no network writes.

Auth Token

Use a bearer token for a user with write access to CARTO_LIBRARY_ID. Do not store the token in repo files. Supply it through your shell environment or another local secret mechanism.

If the token is invalid or lacks the required library permissions, the suite fails early on its first live command.

Static test tokens expire quickly. For local backend verification, prefer minting a fresh test-extension token:

curl -s -X POST http://127.0.0.1:8000/api/v1/auth/test-extension/token \
  -H 'content-type: application/json' \
  -H 'origin: http://localhost:3000' \
  -d '{"mock_user_id":"firebase|alice001"}'

That route currently returns expires_in: 900, so long live suites should use a freshly minted token instead of a stale .env value.

Cleanup And Safety

The suite creates resources with an it-carto-<runId>-... prefix and tracks created ids in memory during the run.

Cleanup behavior:

• items are deleted first
• folders are deleted deepest-first
• cleanup runs automatically after write tests

If CARTO_KEEP_ARTIFACTS=1 is set, cleanup is skipped so you can inspect the created backend state manually.

The suite is designed for a writable dev or staging-style library. Do not point it at production by default.

Verification Status

• Wrapper construction tests cover all wrapper-backed tools.
• Contract tests cover every supported command family against backend route shapes.
• Live smoke covers every supported command family except item upload, which is behind CARTO_LIVE_SMOKE_UPLOAD=1 because it depends on a storage-backed backend environment.