npm package: @iminds/carto
Description: Carto knowledge system extension for mindkit
Latest version: 0.4.0

# @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:

```bash
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:

```bash
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

```bash
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:

```bash
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.