@raggle-ai/local

Local project discovery and expansion logic for Raggle Scout.

Install

npm install @raggle-ai/local

Entry points

• @raggle-ai/local — compatibility surface for existing consumers
• @raggle-ai/local/search — search indexes, query helpers, and live/user search lifecycle; preferred for new search integrations
• @raggle-ai/local/sessions
• @raggle-ai/local/acp
• @raggle-ai/local/service-client — generated typed Fetch client
• @raggle-ai/local/service — start and close the local HTTP service
• @raggle-ai/local/folder-metadata — synchronous local folder/icon resolution. resolveFolderMetadata(folder, { repositoryRoot?, fallbackIcon? }) returns the resolved folder, repository root, and optional icon with local, repository, or cache provenance. Nearest local icons win, then ancestors up to the repository root, then the opaque catalog fallback. Without a repository, only the requested folder is searched. No network or image encoding occurs during resolution. Asset encoding remains internal to feed/metadata adapters.
• @raggle-ai/local/mcp — process startup entry; importing it starts the stdio MCP server

The library includes its native Node add-on and resolves it relative to the installed package. Internal src and dist paths are not public exports.

Automatic project emoji

Project loaders, cache readers, and search results include emoji?: string by default when no image icon is available. The value is a Unicode emoji, not an image path. hasIcon continues to describe images only.

resolveProjectEmoji({ worktree, name?, icon?, tags?, keywords?, repositoryRoot?, parentProjectName? }) provides the same selection for other consumers. It checks the name and folder, then tags and keywords, then parent folders within the repository. Whole words and longer phrases are matched against a generated catalog of English Emojibase labels, country names, Emojibase/GitHub shortcodes, CLDR tags, and Emojilib keywords. Country names and exact labels take priority over broad keywords. Short country codes only match a complete name or tag, so contact-us does not select 🇺🇸. Tied matches remain unresolved instead of using dataset order. A small product preference map selects common meanings such as music → 🎵, greek → 🇬🇷, and british → 🇬🇧.

The catalog is loaded once per process without network access. Greece selects 🇬🇷, UK selects 🇬🇧, and unknown topics select 📁. Full flag, variation-selector, and joined emoji sequences are preserved. Image icons take priority. Selection does not depend on the search query.

Builds generate src/generated/project-emoji.json and THIRD_PARTY_NOTICES.md from pinned, development-only datasets. The published package contains the catalog and required license notices; it does not require Emojibase or Emojilib at runtime. To refresh the data, update the exact development dependency versions, run npm run generate:emoji --workspace @raggle-ai/local, review the generated changes, and run npm run test:project-emoji from the repository root. Do not edit the generated catalog manually.

Project display names and folder metadata

Configure the shared formatter once per adapter:

import { createProjectPresenter } from "@raggle-ai/local";

const presentProject = createProjectPresenter({ addEmojis: true });
const display = presentProject(project);
// display.name: "🎵 music" when no image exists
// display.path: the unchanged folder or Markdown file path
// display.metadata.icon?.path: the resolved local, inherited, or catalog image

The formatter reads current metadata from the local folder to open, or the containing folder for a Markdown result. Images take priority over generated emoji. Input names, paths, and search data do not change. With addEmojis omitted or false, display.name stays plain and display.emoji is available for a separate icon component. The project feed enables inline emoji. Raycast and the TUI use the separate emoji field so emoji and image icons occupy the same display column. Pass addEmojis: false to listLocalProjectFeed or buildProjectFeedPresentation when feed names will be indexed, as in the HTTP service.

The CLI is installed separately with npm install -g @raggle-ai/cli. This package no longer owns rgl or raggle-local.

Build from the repository root with npm run build:all before running npm --workspace @raggle-ai/local test. See the repository documentation for development and release details.