binarii-marketplace

VS Code extension that provides a marketplace UI for librarii skills and agents, plus a visual process editor for business processes.

What it does

Three main features, accessible via the librarii icon in the activity bar:

1. AI catalog — browse, install, customize, and create skills and agents from the librarii public registry (or as local custom items)
2. Processes — visual editor for business process maps with sub-processes, swimlanes, skills/deliverables on steps
3. Deliverables — manage project artifacts (title, description, link) and attach them to process steps

Requirements

• VS Code 1.85+
• Node.js 18+
• A workspace folder open (most features need one)

Quick start (development)

git clone https://github.com/binarii-io/binarii-marketplace
cd binarii-marketplace
npm install

Then in VS Code:

1. Open the repo folder
2. Press F5 → opens an Extension Development Host with test-workspace/ loaded
3. Click the librarii icon in the activity bar

The librarii registry is fetched anonymously from the public GitHub repo (60 req/h/IP). If you're already signed in to GitHub in VS Code, the extension reuses that session silently to raise the limit to 5000 req/h — no popup.

Repo structure

binarii-marketplace/
  src/
    extension.ts                 # Activation, command registration, file watchers
    github.ts                    # GitHub API calls (fetch registry/skills/agents)
    workspace.ts                 # Workspace path helpers, installed manifest readers
    types.ts                     # Shared types (SkillEntry, AgentEntry, ProcessMap, etc.)
    installer.ts                 # Install/uninstall skills + agents on disk
    resolver.ts                  # Apply overrides → write resolved files + agent symlinks
    override.ts                  # Override engine (replace/append/prepend on SKILL.md sections)
    customSkill.ts               # CRUD for locally-created custom skills
    deliverables.ts              # CRUD for deliverables stored as JSON files

    panels/
      SidebarProvider.ts         # Webview sidebar (AI/Processes/Deliverables tabs)
      MarketplacePanel.ts        # Main panel for skill detail / customize / create
      ProcessEditorPanel.ts      # CustomTextEditorProvider for *.process.json
      processCanvasHtml.ts       # The process canvas webview (single big HTML/JS string)
      webviewHtml.ts             # The MarketplacePanel webview (single big HTML/JS string)
      skillParser.ts             # Extract sections from a SKILL.md (used by override editor)

  media/icon.svg                 # Activity bar icon
  docs/                          # Specs and integration notes
  test-workspace/                # Workspace used when launching the dev extension (gitignored)
  out/                           # Compiled JS (gitignored)
  package.json                   # Extension manifest (commands, contributions, deps)
  tsconfig.json

What lives where (mental model)

• Backend = TypeScript modules in src/ outside panels/. They handle disk I/O, GitHub fetches, and state management. They don't know about HTML.
• Panels = WebviewProviders in src/panels/. They render HTML, accept user actions, talk to the backend via postMessage. The webviews are deliberately written as single HTML strings (no bundler, no framework) — easy to read, no build step beyond tsc.
• The user's project is read/written in 4 places:
  • .librarii/skills/ — resolved skill files (base + customizations) read by Claude/Cursor/Gemini
  • .librarii/agents/ — resolved agent files
  • .librarii/installed.json and .librarii/installed-agents.json — manifests of what's installed
  • processes/ and deliverables/ — user-facing files the user can directly edit

Architecture overview

Two repos, one product

• binarii-io/librarii (public) — the catalog: a registry of skills + agents, fetched at runtime via the GitHub Contents API. Single source of truth for the catalog.
• binarii-io/binarii-marketplace (this repo) — the VS Code extension that consumes the registry and provides the UI.

Data flow when a user installs a skill

Sidebar ──click "Install"──▶ MarketplacePanel.doInstall
                                  │
                                  ▼
                            github.fetchSkillContent
                                  │
                                  ▼
                        installer.installSkillFromContent
                                  │
                                  ▼
                        resolver.resolveOneFromContent
                          (applies any overrides)
                                  │
                                  ▼
                        resolver.configureAgents
                          (creates symlinks for Claude/Gemini)
                                  │
                                  ▼
                        Writes:
                        - .librarii/skills/{name}/SKILL.md
                        - .librarii/installed.json
                        - .claude/skills/{name} → symlink
                        - .gemini/skills/{name} → symlink

How customizations work

1. Original SKILL.md is never modified.
2. User customizations are stored in .librarii/overrides/{skillName}/override.json as a list of section-targeted operations (replace, append, prepend).
3. At save time, resolver.resolveOneFromContent reads the base + applies the override → writes the merged result to .librarii/skills/{name}/SKILL.md.
4. The agents (Claude, Cursor, Gemini) only ever see the merged result — they have no concept of "customization".

How the process editor talks to the document

ProcessEditorPanel.ts is a CustomTextEditorProvider for *.process.json files. Important quirks:

• It does NOT use VS Code's TextDocument API for saves. It writes directly via fs.writeFileSync. This avoids a long-standing bug where applyEdit + document.save() triggers cascading reload events that reset the webview state. See the comment in resolveCustomTextEditor.
• The webview holds the source of truth in memory. The backend writes to disk on {type: 'save'} messages.
• When VS Code reopens a .process.json (after switching tabs), it recreates the webview. The webview signals readiness with {type: 'ready'} before the backend sends loadProcess. Don't post loadProcess directly after setting HTML — the script may not have finished loading.

State persistence

Symlinks for agent compatibility

Each install/resolve runs configureAgents(workspace) which creates symlinks:

• .claude/skills/{name} → .librarii/skills/{name}
• .claude/agents/{name} → .librarii/agents/{name}
• .gemini/skills/{name} → .librarii/skills/{name}
• .gemini/agents/{name} → .librarii/agents/{name}

Plus updates .vscode/settings.json to set chat.pluginLocations to .librarii.

This is the integration point for Claude Code, Cursor (eventually), Gemini CLI. The agents read from their expected paths, unaware that we're managing them.

How to add a feature

A typical feature touches 3 layers:

1. Type in src/types.ts if you're adding new data
2. Backend module in src/ for disk I/O / GitHub fetch / business logic
3. Webview panel in src/panels/:
   • Add HTML/CSS to the panel's HTML generator
   • Add a JS function that posts a message to the backend
   • Add a case in the onDidReceiveMessage handler
   • The backend handler calls into a backend module and posts a response message

Adding a new sidebar tab (example pattern)

1. In SidebarProvider.ts HTML, add a new <div class="tab" data-tab="...">
2. Add the corresponding if (currentTab === '...') branch in render() and switchTab
3. Add a render{TabName}() function and a state variable
4. In sendData() (backend), fetch the data and postMessage({ type: '...' })
5. In the webview's window.addEventListener('message'), store the data and call render() if needed

Adding a new step property in the process editor

1. Add the field to ProcessStep in types.ts
2. In processCanvasHtml.ts:
   • Add an input/control in the side panel HTML
   • Wire it in renderSidePanel() with oninput → mutate step.field → save()
   • If the property affects the step card, render it in renderSteps()

Development conventions

File-saving approach

Always write directly with fs.writeFileSync for files we own. Don't use vscode.workspace.applyEdit + document.save() — it triggers reload cascades that break webviews. The only exception is when the file IS a VS Code text document being actively edited.

Webviews are HTML strings

Webviews are single HTML strings (HTML + CSS + JS) returned from a function. No bundler, no React, no framework. Reasons:

• Zero build complexity beyond tsc
• Easy to read and modify (no JSX-to-HTML mental translation)
• Webviews are isolated frames, so leaking globals doesn't matter
• The complexity stays manageable because each panel has a focused scope

If a panel grows beyond ~1500 lines, consider splitting it (extract sub-helpers as separate exported HTML fragments returned by helper functions).

Messaging contract (webview ↔ backend)

Every cross-boundary message is { type: string, ...data }. Conventions:

• requestX / xList — pull pattern (webview asks, backend replies)
• saveX — webview sends data, backend writes
• xSaved / xUpdated — backend acknowledges and may send refreshed data
• openX — request the backend to open something (file, link, panel)

Refresh patterns

• Sidebar refresh is centralized: call vscode.commands.executeCommand("librarii.refresh") from anywhere to force the sidebar to re-fetch and re-render.
• Process canvas refresh stays local to its webview; the backend never re-pushes the document state during an edit session (would reset navigation/selection).
• Side panel re-render after data change must be explicit. Mutate state → call renderSidePanel() + renderSteps() + renderConnections() as needed. There's no auto-binding.

CSS / theming

All colors come from VS Code CSS vars (var(--vscode-...)) with fallbacks. Custom semantic vars are defined at the top of each webview style block (--bg, --fg, --accent, --success, etc.). Theme switches Just Work.

For badges and category colors (skill blue, deliverable purple, agent orange, etc.) we use semi-transparent rgba over VS Code vars.

Auto-save and debounce

The process editor uses 300ms debounce for save (save() function in processCanvasHtml.ts). Inputs use oninput so changes apply as you type, but writes batch.

The override editor in MarketplacePanel uses 600ms debounce on textareas + immediate save on toggle/mode change/blur.

Common gotchas

"The webview doesn't update after save"

The backend writes to disk but the webview keeps stale state. Either:

• Call vscode.commands.executeCommand("librarii.refresh") for the sidebar
• Re-send the relevant data message manually to the open panel

"Adding a new step shifts everything"

Browsers can scroll containers with overflow: hidden if focus moves to an element off-screen. We mitigate via fixScroll() (resets scrollLeft/scrollTop) and focus({ preventScroll: true }) everywhere we focus inputs in the canvas.

"Custom editor reloads everything when I save"

Don't use applyEdit + document.save(). Use fs.writeFileSync directly. See ProcessEditorPanel.ts.

"Inline event handlers (onclick="foo()") and quotes"

Webview HTML is built via string concatenation. When passing strings into inline handlers, they MUST be properly escaped to avoid breaking the JS or enabling XSS-like glitches. Use encodeURIComponent for paths/IDs, escape ' for inline strings. Example pattern in the codebase: onclick="openProcess('${encodeURIComponent(filePath)}')".

"Sub-process navigation breaks after save"

Don't ever respond to loadProcess more than once on the same webview instance. We have a loaded flag in processCanvasHtml.ts that ignores subsequent loads. The webview is the source of truth during the session.

Versioning of the librarii registry

Skills and agents have versions in their SKILL.md / AGENT.md frontmatter. The librarii repo uses git tags for repo-level releases (v1.0.0, v1.1.0...). To pin a specific skill version, the extension can fetch from a specific tag using the GitHub Contents API (?ref=tag).

Currently the extension fetches from a single ref (set in github.ts DEFAULT_REF). Add per-skill version selection later by exposing a UI for it.

Building and packaging

npm run build           # one-shot compile
npm run watch           # watch mode

To package as a .vsix for distribution:

npx vsce package

(Not currently set up in CI.)

Contributing workflow

1. Branch from main. Never commit directly to main.
2. Write small, focused commits. The commit message should explain why, not just what.
3. Don't co-sign commits. Don't add Co-Authored-By: Claude ....
4. Don't push without explicit permission when working with an AI assistant.
5. Test your changes by F5-launching the extension and walking through the affected flow.
6. Update this README and docs/ if you change architecture.

Roadmap / known TODOs

• Per-skill version pinning UI
• Smarter external process refs (use process ID, not file path, to survive renames)
• Deliverable templates / categories
• Agent skill resolution (currently agents reference skills by name; no validation that referenced skills exist)
• Service blueprint mode for swimlanes (line of interaction / line of visibility presets)
• Export process maps to Excalidraw / Draw.io for sharing outside VS Code

License

Private — internal binarii project.