@agentrhq/webcmd 0.2.2 → 0.2.4

package/dist/src/plugin-catalog.js

@@ -0,0 +1,178 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getEnabledPlugins, isMonorepo } from './plugin-manifest.js';
+import { findPackageRoot } from './package-paths.js';
+const MODULE_FILE = fileURLToPath(import.meta.url);
+const CATALOG_FILENAME = 'plugin-catalog.json';
+export function getUserPluginCatalogPath(homeDir = os.homedir()) {
+    return path.join(homeDir, '.webcmd', CATALOG_FILENAME);
+}
+export function getPackagedPluginCatalogPath(packageRoot = findPackageRoot(MODULE_FILE)) {
+    return path.join(packageRoot, CATALOG_FILENAME);
+}
+export function readCatalog(options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const userPath = getUserPluginCatalogPath(homeDir);
+    if (!fs.existsSync(userPath))
+        seedUserCatalog(options.packageRoot, homeDir);
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(userPath, 'utf-8'));
+    }
+    catch (err) {
+        throw new Error(`Malformed plugin catalog at ${userPath}: ${errorMessage(err)}`);
+    }
+    return normalizeCatalog(parsed, userPath);
+}
+export function writeCatalog(catalog, options = {}) {
+    const userPath = getUserPluginCatalogPath(options.homeDir ?? os.homedir());
+    fs.mkdirSync(path.dirname(userPath), { recursive: true });
+    fs.writeFileSync(userPath, `${JSON.stringify(catalog, null, 2)}\n`);
+}
+export function deriveGithubCatalogSource(source) {
+    const parsed = parseGithubSource(source);
+    if (!parsed)
+        throw new Error(`Unsupported catalog source "${source}". Use github:owner/repo.`);
+    const { owner, repo } = parsed;
+    return {
+        id: `${owner}/${repo}`,
+        source,
+        manifestUrl: `https://raw.githubusercontent.com/${owner}/${repo}/main/webcmd-plugin.json`,
+    };
+}
+export async function addCatalogSource(source, options = {}) {
+    const entry = deriveGithubCatalogSource(source);
+    const catalog = readCatalog(options);
+    const duplicate = catalog.sources.find((existing) => (existing.id === entry.id || existing.source === entry.source || existing.manifestUrl === entry.manifestUrl));
+    if (duplicate)
+        throw new Error(`Catalog source already exists: ${duplicate.id}`);
+    const manifest = await fetchManifest(entry, options.fetchJson);
+    validateMarketplaceManifest(manifest, entry.manifestUrl);
+    catalog.sources.push(entry);
+    writeCatalog(catalog, options);
+    return entry;
+}
+export function removeCatalogSource(id, options = {}) {
+    const catalog = readCatalog(options);
+    const index = catalog.sources.findIndex((source) => source.id === id);
+    if (index < 0)
+        throw new Error(`Catalog source not found: ${id}`);
+    const [removed] = catalog.sources.splice(index, 1);
+    writeCatalog(catalog, options);
+    return removed;
+}
+export function flattenPluginManifest(source, manifest) {
+    if (isMonorepo(manifest)) {
+        return getEnabledPlugins(manifest).map(({ name, entry }) => ({
+            name,
+            description: entry.description,
+            version: entry.version,
+            sourceId: source.id,
+            installSource: `${source.source}/${name}`,
+            webcmd: entry.webcmd ?? manifest.webcmd,
+        }));
+    }
+    if (!manifest.name)
+        return [];
+    return [{
+            name: manifest.name,
+            description: manifest.description,
+            version: manifest.version,
+            sourceId: source.id,
+            installSource: source.source,
+            webcmd: manifest.webcmd,
+        }];
+}
+export async function searchCatalogPlugins(catalog, options = {}) {
+    const plugins = [];
+    const errors = [];
+    await Promise.all(catalog.sources.map(async (source) => {
+        try {
+            const manifest = await fetchManifest(source, options.fetchJson);
+            validateMarketplaceManifest(manifest, source.manifestUrl);
+            plugins.push(...flattenPluginManifest(source, manifest));
+        }
+        catch (err) {
+            errors.push({ sourceId: source.id, manifestUrl: source.manifestUrl, message: errorMessage(err) });
+        }
+    }));
+    const query = options.query?.trim().toLowerCase();
+    const filtered = query
+        ? plugins.filter((plugin) => `${plugin.name} ${plugin.description ?? ''}`.toLowerCase().includes(query))
+        : plugins;
+    filtered.sort((a, b) => a.name.localeCompare(b.name));
+    errors.sort((a, b) => a.sourceId.localeCompare(b.sourceId));
+    return { plugins: filtered, errors };
+}
+function seedUserCatalog(packageRoot, homeDir) {
+    const packagedPath = getPackagedPluginCatalogPath(packageRoot);
+    const userPath = getUserPluginCatalogPath(homeDir);
+    if (!fs.existsSync(packagedPath))
+        throw new Error(`Packaged plugin catalog not found: ${packagedPath}`);
+    fs.mkdirSync(path.dirname(userPath), { recursive: true });
+    fs.copyFileSync(packagedPath, userPath);
+}
+function normalizeCatalog(value, filePath) {
+    if (!isRecord(value))
+        throw new Error(`Malformed plugin catalog at ${filePath}: expected object`);
+    if (value.version !== 1)
+        throw new Error(`Malformed plugin catalog at ${filePath}: expected version 1`);
+    if (!Array.isArray(value.sources))
+        throw new Error(`Malformed plugin catalog at ${filePath}: expected sources array`);
+    return {
+        version: 1,
+        sources: value.sources.map((source, index) => normalizeCatalogSource(source, `${filePath} sources[${index}]`)),
+    };
+}
+function normalizeCatalogSource(value, label) {
+    if (!isRecord(value))
+        throw new Error(`Malformed plugin catalog at ${label}: expected object`);
+    if (typeof value.id !== 'string' || !value.id)
+        throw new Error(`Malformed plugin catalog at ${label}: expected id`);
+    if (typeof value.source !== 'string' || !value.source)
+        throw new Error(`Malformed plugin catalog at ${label}: expected source`);
+    if (typeof value.manifestUrl !== 'string' || !value.manifestUrl)
+        throw new Error(`Malformed plugin catalog at ${label}: expected manifestUrl`);
+    const github = parseGithubSource(value.source);
+    return {
+        id: github ? `${github.owner}/${github.repo}` : value.id,
+        source: value.source,
+        manifestUrl: value.manifestUrl,
+    };
+}
+function parseGithubSource(source) {
+    const match = /^github:([\w.-]+)\/([\w.-]+)$/.exec(source);
+    if (!match)
+        return null;
+    return { owner: match[1], repo: match[2] };
+}
+async function fetchManifest(source, fetchJson = defaultFetchJson) {
+    const value = await fetchJson(source.manifestUrl);
+    if (!isRecord(value))
+        throw new Error(`Invalid plugin manifest at ${source.manifestUrl}: expected object`);
+    return value;
+}
+function validateMarketplaceManifest(manifest, manifestUrl) {
+    if (isMonorepo(manifest)) {
+        if (getEnabledPlugins(manifest).length === 0) {
+            throw new Error(`Invalid plugin manifest at ${manifestUrl}: no enabled plugins`);
+        }
+        return;
+    }
+    if (!manifest.name)
+        throw new Error(`Invalid plugin manifest at ${manifestUrl}: missing name or plugins`);
+}
+async function defaultFetchJson(url) {
+    const response = await fetch(url);
+    if (!response.ok)
+        throw new Error(`HTTP ${response.status} ${response.statusText}`.trim());
+    return response.json();
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/src/plugin-catalog.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/plugin-catalog.test.js

@@ -0,0 +1,95 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { addCatalogSource, deriveGithubCatalogSource, flattenPluginManifest, getUserPluginCatalogPath, readCatalog, removeCatalogSource, searchCatalogPlugins, } from './plugin-catalog.js';
+describe('plugin catalog', () => {
+    let tmpDir;
+    let packageRoot;
+    let homeDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-plugin-catalog-'));
+        packageRoot = path.join(tmpDir, 'package');
+        homeDir = path.join(tmpDir, 'home');
+        fs.mkdirSync(packageRoot, { recursive: true });
+        fs.mkdirSync(homeDir, { recursive: true });
+        fs.writeFileSync(path.join(packageRoot, 'plugin-catalog.json'), JSON.stringify({
+            version: 1,
+            sources: [{
+                    id: 'agentrhq/webcmd',
+                    source: 'github:agentrhq/webcmd',
+                    manifestUrl: 'https://raw.githubusercontent.com/agentrhq/webcmd/main/webcmd-plugin.json',
+                }],
+        }));
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it('seeds the user catalog from the packaged default', () => {
+        const catalog = readCatalog({ packageRoot, homeDir });
+        expect(catalog.sources).toEqual([{ id: 'agentrhq/webcmd', source: 'github:agentrhq/webcmd', manifestUrl: 'https://raw.githubusercontent.com/agentrhq/webcmd/main/webcmd-plugin.json' }]);
+        expect(fs.existsSync(getUserPluginCatalogPath(homeDir))).toBe(true);
+    });
+    it('derives catalog metadata from github shorthand', () => {
+        expect(deriveGithubCatalogSource('github:other-org/webcmd-travel-plugins')).toEqual({
+            id: 'other-org/webcmd-travel-plugins',
+            source: 'github:other-org/webcmd-travel-plugins',
+            manifestUrl: 'https://raw.githubusercontent.com/other-org/webcmd-travel-plugins/main/webcmd-plugin.json',
+        });
+    });
+    it('adds and removes catalog sources in the user catalog', async () => {
+        const fetchJson = async () => ({ name: 'travel', description: 'Travel tools' });
+        const added = await addCatalogSource('github:other-org/webcmd-travel-plugins', { packageRoot, homeDir, fetchJson });
+        expect(added.id).toBe('other-org/webcmd-travel-plugins');
+        expect(readCatalog({ packageRoot, homeDir }).sources.map((source) => source.id)).toEqual([
+            'agentrhq/webcmd',
+            'other-org/webcmd-travel-plugins',
+        ]);
+        removeCatalogSource('other-org/webcmd-travel-plugins', { packageRoot, homeDir });
+        expect(readCatalog({ packageRoot, homeDir }).sources.map((source) => source.id)).toEqual(['agentrhq/webcmd']);
+    });
+    it('rejects duplicate catalog sources', async () => {
+        const fetchJson = async () => ({ name: 'travel', description: 'Travel tools' });
+        await addCatalogSource('github:other-org/webcmd-travel-plugins', { packageRoot, homeDir, fetchJson });
+        await expect(addCatalogSource('github:other-org/webcmd-travel-plugins', { packageRoot, homeDir, fetchJson })).rejects.toThrow('already exists');
+    });
+    it('flattens monorepo manifests into installable rows', () => {
+        const rows = flattenPluginManifest({
+            id: 'agentrhq/webcmd',
+            source: 'github:agentrhq/webcmd',
+            manifestUrl: 'https://example.com/webcmd-plugin.json',
+        }, {
+            webcmd: '>=0.2.0',
+            plugins: {
+                skyscanner: { path: 'plugins/skyscanner', version: '0.1.0', description: 'Flights', webcmd: '>=0.2.1' },
+                disabled: { path: 'plugins/disabled', disabled: true },
+            },
+        });
+        expect(rows).toEqual([{ name: 'skyscanner', description: 'Flights', version: '0.1.0', sourceId: 'agentrhq/webcmd', installSource: 'github:agentrhq/webcmd/skyscanner', webcmd: '>=0.2.1' }]);
+    });
+    it('flattens single-plugin manifests into installable rows', () => {
+        const rows = flattenPluginManifest({
+            id: 'research-tools',
+            source: 'github:someone/research-tools',
+            manifestUrl: 'https://example.com/webcmd-plugin.json',
+        }, { name: 'research-tools', version: '0.1.0', description: 'Research helpers', webcmd: '>=0.2.0' });
+        expect(rows).toEqual([{ name: 'research-tools', description: 'Research helpers', version: '0.1.0', sourceId: 'research-tools', installSource: 'github:someone/research-tools', webcmd: '>=0.2.0' }]);
+    });
+    it('fetches manifests live and preserves remote errors in search output', async () => {
+        const catalog = {
+            version: 1,
+            sources: [
+                { id: 'ok', source: 'github:ok/repo', manifestUrl: 'https://ok.test/webcmd-plugin.json' },
+                { id: 'bad', source: 'github:bad/repo', manifestUrl: 'https://bad.test/webcmd-plugin.json' },
+            ],
+        };
+        const fetchJson = async (url) => {
+            if (url.includes('bad'))
+                throw new Error('network failed');
+            return { plugins: { flights: { path: 'plugins/flights', description: 'Flight search' } } };
+        };
+        const result = await searchCatalogPlugins(catalog, { query: 'flight', fetchJson });
+        expect(result.plugins.map((plugin) => plugin.name)).toEqual(['flights']);
+        expect(result.errors).toEqual([{ sourceId: 'bad', manifestUrl: 'https://bad.test/webcmd-plugin.json', message: 'network failed' }]);
+    });
+});

package/dist/src/release-notes.d.ts

@@ -1,4 +1,4 @@
-export declare const RELEASE_NOTE_SECTIONS: readonly ["Highlights", "Improvements", "Fixes", "Contributors", "Reverts"];
+export declare const RELEASE_NOTE_SECTIONS: readonly ["Highlights", "Improvements", "Fixes", "Adapters", "Reverts"];
 export type ReleaseNoteSection = typeof RELEASE_NOTE_SECTIONS[number];
 export interface PullRequestLabel {
     name: string;
@@ -32,7 +32,9 @@ export interface CompareCommit {
     author?: string | null;
 }
 export type GitRunner = (args: readonly string[]) => Promise<string>;
+export declare function releaseVersionFromTag(tag: string): string;
+export declare function replaceChangelogReleaseNotes(changelog: string, tag: string, notes: string): string;
 export declare function extractPullRequestNumber(message: string): number | null;
 export declare function filterReleasePullRequests(prs: PullRequestDetails[]): PullRequestDetails[];
-export declare function normalizeReleaseNotes(raw: string, contributors: string[]): string;
+export declare function normalizeReleaseNotes(raw: string): string;
 export declare function buildReleaseNotesPrompt(context: ReleaseContext): string;

package/dist/src/release-notes.js

@@ -1,17 +1,64 @@
-export const RELEASE_NOTE_SECTIONS = ['Highlights', 'Improvements', 'Fixes', 'Contributors', 'Reverts'];
+export const RELEASE_NOTE_SECTIONS = [
+    'Highlights',
+    'Improvements',
+    'Fixes',
+    'Adapters',
+    'Reverts',
+];
 const SQUASH_MERGE_PR_NUMBER_PATTERN = /\(#(?<number>\d+)\)\s*$/;
 const MERGE_COMMIT_PR_NUMBER_PATTERN = /^Merge pull request #(?<number>\d+) /;
 const RELEASE_PLEASE_TITLE_PATTERN = /^chore(?:\([^)]+\))?: release(?:\s|$)/;
-function normalizeHandle(handle) {
-    const trimmed = handle.trim();
-    return trimmed.startsWith('@') ? trimmed.slice(1) : trimmed;
+function isNoChangeContent(content) {
+    const lines = content
+        .split(/\r?\n/)
+        .map((line) => line.trim().replace(/^[-*]\s+/, '').replace(/[.。]+$/, '').trim().toLowerCase())
+        .filter(Boolean);
+    if (lines.length === 0)
+        return true;
+    return lines.every((line) => (line === 'none'
+        || line === 'n/a'
+        || line === 'not applicable'
+        || /^no .*?(?:changes|updates|reverts|fixes|improvements|adapters|highlights)(?: in this release)?$/.test(line)
+        || /^there (?:are|were) no .*?(?:changes|updates|reverts|fixes|improvements|adapters|highlights)(?: in this release)?$/.test(line)));
 }
-function uniqueSortedHandles(handles) {
-    return [...new Set(handles.map(normalizeHandle).filter(Boolean))].sort((left, right) => left.localeCompare(right));
-}
-function formatSectionContent(content) {
+function normalizeSectionContent(content) {
     const trimmed = content?.trim();
-    return trimmed && trimmed.length > 0 ? trimmed : 'None.';
+    if (!trimmed || isNoChangeContent(trimmed))
+        return null;
+    return trimmed;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function formatReleaseNotesForChangelog(notes) {
+    const trimmed = notes.trim();
+    if (!trimmed)
+        return '';
+    return trimmed.replace(/^##\s+/gm, '### ');
+}
+export function releaseVersionFromTag(tag) {
+    const value = tag.trim();
+    if (value.startsWith('webcmd-v'))
+        return value.slice('webcmd-v'.length);
+    if (value.startsWith('v'))
+        return value.slice(1);
+    return value;
+}
+export function replaceChangelogReleaseNotes(changelog, tag, notes) {
+    const version = releaseVersionFromTag(tag);
+    const headingPattern = new RegExp(`^## \\[${escapeRegExp(version)}\\]\\([^\\n]+\\) \\([^\\n]+\\)\\s*$`, 'm');
+    const headingMatch = headingPattern.exec(changelog);
+    if (!headingMatch) {
+        throw new Error(`Could not find CHANGELOG.md entry for ${version}`);
+    }
+    const headingEnd = headingMatch.index + headingMatch[0].length;
+    const remaining = changelog.slice(headingEnd);
+    const nextReleaseMatch = /\n## \[/.exec(remaining);
+    const releaseEnd = nextReleaseMatch ? headingEnd + nextReleaseMatch.index : changelog.length;
+    const before = changelog.slice(0, headingEnd).trimEnd();
+    const after = changelog.slice(releaseEnd);
+    const suffix = after ? after.replace(/^\n+/, '\n\n') : '\n';
+    return `${before}\n\n${formatReleaseNotesForChangelog(notes)}${suffix}`;
 }
 export function extractPullRequestNumber(message) {
     const firstLine = message.split(/\r?\n/, 1)[0] ?? message;
@@ -57,16 +104,11 @@ function parseReleaseNoteSections(raw) {
     }
     return sections;
 }
-export function normalizeReleaseNotes(raw, contributors) {
+export function normalizeReleaseNotes(raw) {
     const sections = parseReleaseNoteSections(raw);
-    const normalizedContributors = uniqueSortedHandles(contributors).map((handle) => `- @${handle}`);
-    return RELEASE_NOTE_SECTIONS.map((section) => {
-        if (section === 'Contributors') {
-            const content = normalizedContributors.length > 0 ? normalizedContributors.join('\n') : 'None.';
-            return `## ${section}\n${content}`;
-        }
-        const content = formatSectionContent(sections[section]?.join('\n'));
-        return `## ${section}\n${content}`;
+    return RELEASE_NOTE_SECTIONS.flatMap((section) => {
+        const content = normalizeSectionContent(sections[section]?.join('\n'));
+        return content ? [`## ${section}\n${content}`] : [];
     }).join('\n\n');
 }
 function formatPullRequest(pr) {
@@ -90,8 +132,13 @@ export function buildReleaseNotesPrompt(context) {
         `Write user-facing release notes for ${context.tag}.`,
         `Release range: ${context.previousTag}...${context.currentRef}.`,
         'Use only the supplied pull requests below. Do not invent changes or pull in information from elsewhere.',
-        `Required sections: ${RELEASE_NOTE_SECTIONS.map((section) => `## ${section}`).join(', ')}.`,
-        'Each section must be present in the final notes.',
+        `Allowed sections: ${RELEASE_NOTE_SECTIONS.map((section) => `## ${section}`).join(', ')}.`,
+        'Include only sections that have user-visible changes. Omit empty sections entirely; do not write "None", "N/A", or similar placeholder text.',
+        'Do not include a Contributors section.',
+        'In this project, CLI commands and adapters are the same thing. Treat any PR that adds, removes, or changes files under clis/** as an adapter change, even if the PR title says "CLI" instead of "adapter".',
+        'Put new site adapters/CLIs, adapter promotions, adapter hardening, adapter output changes, selector/API updates, and site-specific workflow improvements in ## Adapters.',
+        'Use ## Improvements for non-adapter product, runtime, CLI, docs, or workflow improvements.',
+        'Use ## Reverts only when the release includes actual reverted changes.',
         '',
         `Pull requests included for this release:`,
         prSummaries,

package/dist/src/release-notes.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { RELEASE_NOTE_SECTIONS, buildReleaseNotesPrompt, extractPullRequestNumber, filterReleasePullRequests, normalizeReleaseNotes, } from './release-notes.js';
+import { RELEASE_NOTE_SECTIONS, buildReleaseNotesPrompt, extractPullRequestNumber, filterReleasePullRequests, normalizeReleaseNotes, replaceChangelogReleaseNotes, } from './release-notes.js';
 describe('release notes helpers', () => {
     it('extracts PR numbers from squash and merge commit messages', () => {
         expect(extractPullRequestNumber('feat: add release notes (#123)')).toBe(123);
@@ -17,21 +17,72 @@ describe('release notes helpers', () => {
         ];
         expect(filterReleasePullRequests(prs).map((pr) => pr.number)).toEqual([1]);
     });
-    it('normalizes all required sections and fills empty sections with None', () => {
+    it('normalizes only sections with real release-note content', () => {
         const raw = [
+            '## Highlights',
+            '- Better release notes.',
+            '',
+            '## Improvements',
+            'No improvements.',
+            '',
+            '## Adapters',
+            'No adapter changes.',
+            '',
+            '## Fixes',
+            '- Fixed release fallback.',
+            '',
+            '## Contributors',
+            '- @alice',
+            '',
+            '## Reverts',
+            'There are no reverts in this release.',
+        ].join('\n');
+        const normalized = normalizeReleaseNotes(raw);
+        expect(RELEASE_NOTE_SECTIONS).toEqual(['Highlights', 'Improvements', 'Fixes', 'Adapters', 'Reverts']);
+        expect(normalized).toBe([
             '## Highlights',
             '- Better release notes.',
             '',
             '## Fixes',
             '- Fixed release fallback.',
+        ].join('\n'));
+        expect(normalized).not.toContain('## Improvements');
+        expect(normalized).not.toContain('## Contributors');
+        expect(normalized).not.toContain('## Reverts');
+        expect(normalized).not.toContain('None.');
+    });
+    it('replaces a matching changelog release entry with generated notes', () => {
+        const changelog = [
+            '# Changelog',
+            '',
+            '## [0.2.3](https://github.com/agentrhq/webcmd/compare/webcmd-v0.2.2...webcmd-v0.2.3) (2026-07-09)',
+            '',
+            '',
+            '### Features',
+            '',
+            '* release-please generated note',
+            '',
+            '## [0.2.2](https://github.com/agentrhq/webcmd/compare/webcmd-v0.2.1...webcmd-v0.2.2) (2026-07-08)',
+            '',
+            '### Bug Fixes',
+            '',
+            '* older note',
+            '',
+        ].join('\n');
+        const notes = [
+            '## Highlights',
+            '- Better release notes.',
+            '',
+            '## Adapters',
+            '- Improved district checkout.',
         ].join('\n');
-        const normalized = normalizeReleaseNotes(raw, ['alice', 'bob']);
-        for (const section of RELEASE_NOTE_SECTIONS) {
-            expect(normalized).toContain(`## ${section}`);
-        }
-        expect(normalized).toContain('## Improvements\nNone.');
-        expect(normalized).toContain('## Contributors\n- @alice\n- @bob');
-        expect(normalized).toContain('## Reverts\nNone.');
+        const updated = replaceChangelogReleaseNotes(changelog, 'webcmd-v0.2.3', notes);
+        expect(updated).toContain('## [0.2.3]');
+        expect(updated).toContain('### Highlights\n- Better release notes.');
+        expect(updated).toContain('### Adapters\n- Improved district checkout.');
+        expect(updated).not.toContain('release-please generated note');
+        expect(updated).toContain('## [0.2.2]');
+        expect(updated).toContain('* older note');
     });
     it('builds a prompt grounded in the exact release range and PR list', () => {
         const context = {
@@ -56,6 +107,13 @@ describe('release notes helpers', () => {
         expect(prompt).toContain('PR #42: feat: add docs scaffold');
         expect(prompt).toContain('docs/docs.json');
         expect(prompt).toContain('## Highlights');
+        expect(prompt).toContain('## Adapters');
+        expect(prompt).not.toContain('## Contributors');
+        expect(prompt).toContain('Omit empty sections entirely');
+        expect(prompt).toContain('Do not include a Contributors section');
+        expect(prompt).toContain('CLI commands and adapters are the same thing');
+        expect(prompt).toContain('files under clis/** as an adapter change');
+        expect(prompt).toContain('Put new site adapters/CLIs, adapter promotions, adapter hardening');
         expect(prompt).toContain('## Reverts');
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentrhq/webcmd",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Turn websites, browser sessions, desktop apps, and local tools into deterministic CLI surfaces for humans and AI agents.",
   "engines": {
     "node": ">=20.0.0"
@@ -32,6 +32,7 @@
     "clis/",
     "skills/**",
     "cli-manifest.json",
+    "plugin-catalog.json",
     "scripts/",
     "README.md",
     "LICENSE",

package/plugin-catalog.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "sources": [
+    {
+      "id": "agentrhq/webcmd",
+      "source": "github:agentrhq/webcmd",
+      "manifestUrl": "https://raw.githubusercontent.com/agentrhq/webcmd/main/webcmd-plugin.json"
+    }
+  ]
+}

package/scripts/generate-release-notes.ts

@@ -1,4 +1,5 @@
 import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import { GoogleGenAI } from '@google/genai';
 import {
@@ -6,6 +7,7 @@ import {
   extractPullRequestNumber,
   filterReleasePullRequests,
   normalizeReleaseNotes,
+  replaceChangelogReleaseNotes,
   type PullRequestDetails,
   type ReleaseContext,
 } from '../src/release-notes.js';
@@ -191,8 +193,29 @@ async function generateText(prompt: string, model: string, apiKey: string): Prom
   return text;
 }
 
-function contributorHandles(pullRequests: PullRequestDetails[]): string[] {
-  return pullRequests.flatMap((pr) => (pr.author?.login ? [pr.author.login] : []));
+function updateChangelog(tag: string | undefined, notesPath: string | undefined, changelogPath: string | undefined, io: Io): number {
+  if (!tag || !notesPath) {
+    io.writeStderr('Usage: generate-release-notes --update-changelog <tag> <notes-file> [changelog-file]\n');
+    return 1;
+  }
+
+  const targetChangelogPath = changelogPath ?? 'CHANGELOG.md';
+
+  try {
+    const notes = readFileSync(notesPath, 'utf8');
+    const changelog = readFileSync(targetChangelogPath, 'utf8');
+    const updated = replaceChangelogReleaseNotes(changelog, tag, notes);
+    if (updated !== changelog) {
+      writeFileSync(targetChangelogPath, updated);
+    }
+
+    io.writeStdout(`Updated ${targetChangelogPath} for ${tag}\n`);
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    io.writeStderr(`CHANGELOG.md update failed: ${message}\n`);
+    return 1;
+  }
 }
 
 export async function runGenerateReleaseNotes(
@@ -201,6 +224,10 @@ export async function runGenerateReleaseNotes(
   deps: RunDependencies = {},
   io: Io = DEFAULT_IO,
 ): Promise<number> {
+  if (argv[2] === '--update-changelog') {
+    return updateChangelog(argv[3], argv[4], argv[5], io);
+  }
+
   const tag = argv[2];
   if (!tag) {
     io.writeStderr('Usage: generate-release-notes <tag>\n');
@@ -218,8 +245,10 @@ export async function runGenerateReleaseNotes(
     const model = env.GEMINI_RELEASE_NOTES_MODEL || DEFAULT_MODEL;
     const prompt = buildReleaseNotesPrompt(context);
     const raw = await (deps.generateText ?? generateText)(prompt, model, apiKey);
-    const normalized = normalizeReleaseNotes(raw, contributorHandles(context.pullRequests));
-    io.writeStdout(`${normalized}\n`);
+    const normalized = normalizeReleaseNotes(raw);
+    if (normalized) {
+      io.writeStdout(`${normalized}\n`);
+    }
     return 0;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);

package/skills/webcmd-adapter-author/SKILL.md

@@ -194,6 +194,14 @@ Check these off step by step:
         [ ] `fixtures/<cmd>-<YYYYMMDDHHMM>.json`: save one complete endpoint response sample after removing cookies, tokens, and private user fields. Use it for later field comparison and offline replay.
         [ ] If debugging dumped temporary files in the repo or adapter directory, such as `.dbg-*.html`, `raw-*.json`, or similar, **delete them before commit**. Those belong in `~/.webcmd/sites/<site>/fixtures/` or `/tmp/`.
 
+[ ] 13. **First command for this site? Stop and ask before building more.**
+        [ ] If this was the site's first command, do not silently keep scaffolding more commands. Ask the user what use cases they have in mind for this site — who the persona is, what they're trying to accomplish end to end.
+        [ ] From the use cases, propose the full set of commands you'd recommend adding, not just the obvious next one. Cover the whole journey the use cases imply (discovery, single-item detail, comparison, account/write actions, etc.), not only what's cheapest to build.
+        [ ] If that set is small (roughly ≤6-8 commands), list it flat and ask the user to confirm or trim it.
+        [ ] If it's large, bucket the commands into named groups (e.g. "Discovery", "Single-item evaluation", "Account actions requiring login") and ask the user which bucket(s) to build first — do not dump an unbucketed wall of commands.
+        [ ] Flag any bucket that needs a capability not yet solved (login/OTP, write access, payment) as its own decision point — e.g. "these need login — how do you want to handle auth?" — separate from the command list itself.
+        [ ] Do not scaffold additional commands until the user has confirmed which ones to build.
+
 ---
 
 ## Fallback Paths
@@ -247,6 +255,7 @@ Check these off step by step:
 - **Persistent sessions keep stale DOM between commands.** `siteSession: 'persistent'` shares one tab per site; leftover modals/drawers from the previous command leak into the next one. State-sensitive write commands (checkout flows) should add `freshPage: true` (new tab, same lease — cookies/login/location survive). Verify session-scoped context (login, selected city/date) *before* side effects, and embed such context in URLs/IDs your command emits for sibling commands. See `references/adapter-template.md` and "Persistent Sessions and State Hygiene" in `docs/authoring.mdx`.
 - For private adapters, write `~/.webcmd/clis/<site>/<name>.js` to avoid a build. Copy to `clis/<site>/<name>.js` only when preparing a PR.
 - Write site memory every round: no memory -> use skill -> produce memory -> next time becomes a five-minute task.
+- **After a site's first command passes verify, stop and ask the user for their use cases before recommending next set of commands.** See Runbook Step 13.
 - **Raw dumps, packet captures, and HTML samples from debugging may only be written to `~/.webcmd/sites/<site>/fixtures/` or `/tmp/`. Never leave `.dbg-*.html`, `raw-*.json`, `sample.*`, or similar temporary files in the repo root, `clis/<site>/`, or the current working directory.**
 - **JSDOM unit-test fixtures (`clis/<site>/__fixtures__/<command>.html`) are the exception.** They are intentional review artifacts committed to the repo, not temporary dumps. Because of that, the quality bar is higher: complete the five steps in `references/jsdom-fixture-pattern.md`, including the mandatory `awk 'NF>0'` blank-line tightening, and reverse-validate once to prove the regression guard can fail.