@agentrhq/webcmd 0.2.5 → 0.3.1

package/dist/src/release-notes.js

@@ -8,6 +8,25 @@ export const RELEASE_NOTE_SECTIONS = [
 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|$)/;
+const CONTRIBUTOR_AVATAR_SIZE = 40;
+const SERVICE_ACCOUNT_HANDLES = new Set([
+    'allcontributors',
+    'copilot-pull-request-reviewer',
+    'dependabot',
+    'github-actions',
+    'release-please',
+    'renovate',
+    'semantic-release-bot',
+    'snyk-bot',
+    'web-flow',
+]);
+function normalizeHandle(handle) {
+    const trimmed = handle.trim();
+    return trimmed.startsWith('@') ? trimmed.slice(1) : trimmed;
+}
+function uniqueSortedHandles(handles) {
+    return [...new Set(handles.map(normalizeHandle).filter(Boolean))].sort((left, right) => left.localeCompare(right));
+}
 function isNoChangeContent(content) {
     const lines = content
         .split(/\r?\n/)
@@ -34,7 +53,11 @@ function formatReleaseNotesForChangelog(notes) {
     const trimmed = notes.trim();
     if (!trimmed)
         return '';
-    return trimmed.replace(/^##\s+/gm, '### ');
+    const lines = trimmed.split(/\r?\n/);
+    if (lines[0]?.startsWith('# ')) {
+        lines[0] = `_${lines[0].replace(/^#\s+/, '').trim()}_`;
+    }
+    return stripContributorAvatarLines(lines.join('\n')).replace(/^##\s+/gm, '### ');
 }
 export function releaseVersionFromTag(tag) {
     const value = tag.trim();
@@ -44,6 +67,150 @@ export function releaseVersionFromTag(tag) {
         return value.slice(1);
     return value;
 }
+function releaseDisplayVersionFromTag(tag) {
+    const version = releaseVersionFromTag(tag);
+    return version.startsWith('v') ? version : `v${version}`;
+}
+function parseReleaseSemver(tag) {
+    const match = releaseVersionFromTag(tag).match(/^v?(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)(?:[-+].*)?$/);
+    if (!match?.groups)
+        return null;
+    return {
+        major: Number(match.groups.major),
+        minor: Number(match.groups.minor),
+        patch: Number(match.groups.patch),
+    };
+}
+export function isMajorRelease(context) {
+    const current = parseReleaseSemver(context.tag);
+    if (!current)
+        return false;
+    const previous = parseReleaseSemver(context.previousTag);
+    if (current.major === 0) {
+        if (current.minor === 0 || current.patch !== 0)
+            return false;
+        if (!previous)
+            return true;
+        return previous.major === 0 && current.minor > previous.minor;
+    }
+    if (!previous)
+        return current.minor === 0 && current.patch === 0;
+    return current.major > previous.major;
+}
+function isServiceAccount(handle) {
+    const normalized = normalizeHandle(handle).toLowerCase();
+    return SERVICE_ACCOUNT_HANDLES.has(normalized)
+        || normalized.endsWith('[bot]')
+        || normalized.endsWith('-bot');
+}
+export function releaseContributorHandles(pullRequests) {
+    return uniqueSortedHandles(pullRequests.flatMap((pr) => (pr.author?.login ? [pr.author.login] : []))).filter((handle) => !isServiceAccount(handle));
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (character) => {
+        switch (character) {
+            case '&':
+                return '&amp;';
+            case '<':
+                return '&lt;';
+            case '>':
+                return '&gt;';
+            case '"':
+                return '&quot;';
+            case "'":
+                return '&#39;';
+            default:
+                return character;
+        }
+    });
+}
+function githubHandleUrl(handle) {
+    return `https://github.com/${encodeURIComponent(handle)}`;
+}
+function formatContributorAvatar(handle) {
+    const escapedHandle = escapeHtml(handle);
+    const encodedHandle = encodeURIComponent(handle);
+    return `<a href="${githubHandleUrl(handle)}" title="@${escapedHandle}"><img src="https://github.com/${encodedHandle}.png?size=${CONTRIBUTOR_AVATAR_SIZE}" width="${CONTRIBUTOR_AVATAR_SIZE}" height="${CONTRIBUTOR_AVATAR_SIZE}" alt="@${escapedHandle}" /></a>`;
+}
+function formatContributorLink(handle) {
+    return `[@${handle}](${githubHandleUrl(handle)})`;
+}
+function formatContributorsSection(handles) {
+    if (handles.length === 0)
+        return null;
+    return [
+        '## Contributors',
+        handles.map(formatContributorAvatar).join(' '),
+        '',
+        handles.map(formatContributorLink).join(' | '),
+    ].join('\n');
+}
+function stripContributorAvatarLines(notes) {
+    return notes
+        .split(/\r?\n/)
+        .filter((line) => !(/<img\b/i.test(line) && /https:\/\/github\.com\/[^"'\s>]+\.png\?size=\d+/.test(line)))
+        .join('\n')
+        .replace(/(^|\n)(## Contributors)\n\n/g, '$1$2\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+function parseMajorReleaseTitle(raw) {
+    for (const line of raw.split(/\r?\n/)) {
+        const titleMatch = line.match(/^#\s+(.+?)\s*$/);
+        if (titleMatch)
+            return titleMatch[1];
+        if (/^##\s+/.test(line))
+            return null;
+    }
+    return null;
+}
+function fallbackMajorReleaseTitle(context) {
+    const releaseText = context.pullRequests.map((pr) => [
+        pr.title,
+        ...pr.labels.map((label) => label.name),
+        ...pr.files.map((file) => file.path),
+    ].join('\n')).join('\n').toLowerCase();
+    if (/\bclis\//.test(releaseText) || /\badapter\b/.test(releaseText) || /\bcli\b/.test(releaseText)) {
+        return 'The Command Surface Expands';
+    }
+    if (/\bbrowser\b|\bcloak\b|\bdaemon\b/.test(releaseText)) {
+        return 'The Browser Runtime Matures';
+    }
+    if (/\bskills?\b/.test(releaseText)) {
+        return 'The Agent Authoring Edition';
+    }
+    if (/\bdocs?\b|\breadme\b/.test(releaseText)) {
+        return 'The Documentation Edition';
+    }
+    if (/\bplugins?\b/.test(releaseText)) {
+        return 'The Plugin System Opens Up';
+    }
+    return 'A New Command Surface';
+}
+function normalizeMajorReleaseTitle(rawTitle, context) {
+    const title = (rawTitle ?? '')
+        .replace(/^webcmd[-\s]+v?\d+\.\d+\.\d+(?:[-+][^:\s]+)?\s*:\s*/i, '')
+        .replace(/^webcmd\s*:\s*/i, '')
+        .replace(/[`*_]/g, '')
+        .replace(/\s+/g, ' ')
+        .replace(/^[#:\-\s]+/, '')
+        .replace(/[.!]+$/, '')
+        .trim();
+    const lowerTitle = title.toLowerCase();
+    if (!title
+        || title.length > 80
+        || lowerTitle === 'none'
+        || lowerTitle === 'n/a'
+        || lowerTitle === 'release notes'
+        || lowerTitle === 'webcmd'
+        || lowerTitle === 'webcmd release') {
+        return fallbackMajorReleaseTitle(context);
+    }
+    return title;
+}
+function formatMajorReleaseHeading(raw, context) {
+    return `# webcmd ${releaseDisplayVersionFromTag(context.tag)}: ${normalizeMajorReleaseTitle(parseMajorReleaseTitle(raw), context)}`;
+}
 export function replaceChangelogReleaseNotes(changelog, tag, notes) {
     const version = releaseVersionFromTag(tag);
     const headingPattern = new RegExp(`^## \\[${escapeRegExp(version)}\\]\\([^\\n]+\\) \\([^\\n]+\\)\\s*$`, 'm');
@@ -104,12 +271,24 @@ function parseReleaseNoteSections(raw) {
     }
     return sections;
 }
-export function normalizeReleaseNotes(raw) {
+export function normalizeReleaseNotes(raw, options = {}) {
     const sections = parseReleaseNoteSections(raw);
-    return RELEASE_NOTE_SECTIONS.flatMap((section) => {
+    const sectionBlocks = RELEASE_NOTE_SECTIONS.flatMap((section) => {
         const content = normalizeSectionContent(sections[section]?.join('\n'));
         return content ? [`## ${section}\n${content}`] : [];
-    }).join('\n\n');
+    });
+    if (sectionBlocks.length === 0)
+        return '';
+    const blocks = [];
+    if (options.context && isMajorRelease(options.context)) {
+        blocks.push(formatMajorReleaseHeading(raw, options.context));
+    }
+    blocks.push(...sectionBlocks);
+    const contributors = options.context ? releaseContributorHandles(options.context.pullRequests) : [];
+    const contributorsSection = formatContributorsSection(contributors);
+    if (contributorsSection)
+        blocks.push(contributorsSection);
+    return blocks.join('\n\n');
 }
 function formatPullRequest(pr) {
     const author = pr.author?.login ?? 'unknown';
@@ -128,11 +307,20 @@ function formatPullRequest(pr) {
 }
 export function buildReleaseNotesPrompt(context) {
     const prSummaries = context.pullRequests.map(formatPullRequest).join('\n\n');
+    const majorReleaseInstructions = isMajorRelease(context)
+        ? [
+            `This is a major release. Start with exactly one H1: # webcmd ${releaseDisplayVersionFromTag(context.tag)}: <Elegant Release Title>.`,
+            'Make the title grand enough to feel memorable, but polished rather than loud. Keep it short, specific to the supplied PRs, and avoid hype words.',
+        ]
+        : [
+            'Do not include a top-level release title.',
+        ];
     return [
         `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.',
         `Allowed sections: ${RELEASE_NOTE_SECTIONS.map((section) => `## ${section}`).join(', ')}.`,
+        ...majorReleaseInstructions,
         '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".',

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, replaceChangelogReleaseNotes, } from './release-notes.js';
+import { RELEASE_NOTE_SECTIONS, buildReleaseNotesPrompt, extractPullRequestNumber, filterReleasePullRequests, isMajorRelease, normalizeReleaseNotes, releaseContributorHandles, 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,6 +17,25 @@ describe('release notes helpers', () => {
         ];
         expect(filterReleasePullRequests(prs).map((pr) => pr.number)).toEqual([1]);
     });
+    it('detects major releases from semver tag ranges', () => {
+        expect(isMajorRelease({ tag: 'webcmd-v2.0.0', previousTag: 'webcmd-v1.9.9' })).toBe(true);
+        expect(isMajorRelease({ tag: 'v3.1.0', previousTag: 'v2.9.9' })).toBe(true);
+        expect(isMajorRelease({ tag: 'webcmd-v0.3.0', previousTag: 'webcmd-v0.2.5' })).toBe(true);
+        expect(isMajorRelease({ tag: 'webcmd-v0.1.0', previousTag: 'webcmd-v0.0.9' })).toBe(true);
+        expect(isMajorRelease({ tag: 'webcmd-v2.1.0', previousTag: 'webcmd-v2.0.0' })).toBe(false);
+        expect(isMajorRelease({ tag: 'webcmd-v0.3.1', previousTag: 'webcmd-v0.3.0' })).toBe(false);
+        expect(isMajorRelease({ tag: 'webcmd-v0.0.1', previousTag: 'webcmd-v0.0.0' })).toBe(false);
+    });
+    it('deduplicates PR author contributors and excludes service accounts', () => {
+        const prs = [
+            { number: 1, title: 'feat: browser polish', author: { login: 'alice' }, labels: [], files: [], url: 'https://example.com/1' },
+            { number: 2, title: 'feat: docs polish', author: { login: '@alice' }, labels: [], files: [], url: 'https://example.com/2' },
+            { number: 3, title: 'chore: release', author: { login: 'github-actions[bot]' }, labels: [], files: [], url: 'https://example.com/3' },
+            { number: 4, title: 'feat: adapter polish', author: { login: 'bob' }, labels: [], files: [], url: 'https://example.com/4' },
+            { number: 5, title: 'chore: release notes', author: { login: 'release-please' }, labels: [], files: [], url: 'https://example.com/5' },
+        ];
+        expect(releaseContributorHandles(prs)).toEqual(['alice', 'bob']);
+    });
     it('normalizes only sections with real release-note content', () => {
         const raw = [
             '## Highlights',
@@ -51,6 +70,92 @@ describe('release notes helpers', () => {
         expect(normalized).not.toContain('## Reverts');
         expect(normalized).not.toContain('None.');
     });
+    it('adds an elegant major release title and visual contributor credits', () => {
+        const context = {
+            tag: 'webcmd-v2.0.0',
+            previousTag: 'webcmd-v1.9.9',
+            currentRef: 'webcmd-v2.0.0',
+            pullRequests: [
+                {
+                    number: 42,
+                    title: 'feat: expand browser adapter coverage',
+                    author: { login: 'alice' },
+                    labels: [{ name: 'feature' }],
+                    files: [{ path: 'clis/github/auth.js' }],
+                    url: 'https://github.com/agentrhq/webcmd/pull/42',
+                },
+                {
+                    number: 43,
+                    title: 'feat: improve release presentation',
+                    author: { login: 'bob' },
+                    labels: [{ name: 'feature' }],
+                    files: [{ path: 'src/release-notes.ts' }],
+                    url: 'https://github.com/agentrhq/webcmd/pull/43',
+                },
+                {
+                    number: 44,
+                    title: 'chore: release automation',
+                    author: { login: 'github-actions[bot]' },
+                    labels: [],
+                    files: [{ path: '.github/workflows/release.yml' }],
+                    url: 'https://github.com/agentrhq/webcmd/pull/44',
+                },
+            ],
+        };
+        const raw = [
+            '# webcmd v2.0.0: The Command Surface Opens',
+            '',
+            '## Highlights',
+            '- Broader adapter authoring workflows.',
+        ].join('\n');
+        const normalized = normalizeReleaseNotes(raw, { context });
+        expect(normalized).toContain('# webcmd v2.0.0: The Command Surface Opens');
+        expect(normalized).toContain('## Contributors');
+        expect(normalized).toContain('<img src="https://github.com/alice.png?size=40" width="40" height="40" alt="@alice" /></a> <a href="https://github.com/bob"');
+        expect(normalized).toContain('[@alice](https://github.com/alice)');
+        expect(normalized).toContain('[@alice](https://github.com/alice) | [@bob](https://github.com/bob)');
+        expect(normalized).not.toContain('github-actions');
+    });
+    it('uses a deterministic major release title fallback when the model omits one', () => {
+        const context = {
+            tag: 'webcmd-v0.3.0',
+            previousTag: 'webcmd-v0.2.5',
+            currentRef: 'webcmd-v0.3.0',
+            pullRequests: [
+                {
+                    number: 42,
+                    title: 'feat: add github adapter',
+                    author: { login: 'alice' },
+                    labels: [{ name: 'feature' }],
+                    files: [{ path: 'clis/github/auth.js' }],
+                    url: 'https://github.com/agentrhq/webcmd/pull/42',
+                },
+            ],
+        };
+        const normalized = normalizeReleaseNotes('## Highlights\n- Added a GitHub adapter.', { context });
+        expect(normalized).toContain('# webcmd v0.3.0: The Command Surface Expands');
+    });
+    it('does not add major release title treatment to minor releases', () => {
+        const context = {
+            tag: 'webcmd-v2.1.0',
+            previousTag: 'webcmd-v2.0.0',
+            currentRef: 'webcmd-v2.1.0',
+            pullRequests: [
+                {
+                    number: 42,
+                    title: 'feat: improve release notes',
+                    author: { login: 'alice' },
+                    labels: [{ name: 'feature' }],
+                    files: [{ path: 'src/release-notes.ts' }],
+                    url: 'https://github.com/agentrhq/webcmd/pull/42',
+                },
+            ],
+        };
+        const normalized = normalizeReleaseNotes('# The Polished Edition\n\n## Highlights\n- Better notes.', { context });
+        expect(normalized).not.toContain('# webcmd v2.1.0');
+        expect(normalized).toContain('## Highlights\n- Better notes.');
+        expect(normalized).toContain('## Contributors');
+    });
     it('replaces a matching changelog release entry with generated notes', () => {
         const changelog = [
             '# Changelog',
@@ -70,24 +175,34 @@ describe('release notes helpers', () => {
             '',
         ].join('\n');
         const notes = [
+            '# webcmd v2.0.0: The Command Surface Expands',
+            '',
             '## Highlights',
             '- Better release notes.',
             '',
             '## Adapters',
             '- Improved district checkout.',
+            '',
+            '## Contributors',
+            '<a href="https://github.com/alice" title="@alice"><img src="https://github.com/alice.png?size=40" width="40" height="40" alt="@alice" /></a>',
+            '',
+            '[@alice](https://github.com/alice)',
         ].join('\n');
         const updated = replaceChangelogReleaseNotes(changelog, 'webcmd-v0.2.3', notes);
         expect(updated).toContain('## [0.2.3]');
+        expect(updated).toContain('_webcmd v2.0.0: The Command Surface Expands_');
         expect(updated).toContain('### Highlights\n- Better release notes.');
         expect(updated).toContain('### Adapters\n- Improved district checkout.');
+        expect(updated).toContain('### Contributors\n[@alice](https://github.com/alice)');
+        expect(updated).not.toContain('<img');
         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 = {
-            tag: 'v0.2.0',
-            previousTag: 'v0.1.1',
+            tag: 'v0.2.1',
+            previousTag: 'v0.2.0',
             currentRef: 'abc123',
             pullRequests: [
                 {
@@ -103,12 +218,13 @@ describe('release notes helpers', () => {
             ],
         };
         const prompt = buildReleaseNotesPrompt(context);
-        expect(prompt).toContain('v0.1.1...abc123');
+        expect(prompt).toContain('v0.2.0...abc123');
         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('Do not include a top-level release title');
         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');
@@ -116,4 +232,27 @@ describe('release notes helpers', () => {
         expect(prompt).toContain('Put new site adapters/CLIs, adapter promotions, adapter hardening');
         expect(prompt).toContain('## Reverts');
     });
+    it('asks for a tasteful H1 title only when building major release notes', () => {
+        const context = {
+            tag: 'webcmd-v0.3.0',
+            previousTag: 'webcmd-v0.2.5',
+            currentRef: 'webcmd-v0.3.0',
+            pullRequests: [
+                {
+                    number: 42,
+                    title: 'feat: expand adapter authoring',
+                    body: 'Adds richer authoring workflows.',
+                    author: { login: 'alice' },
+                    labels: [{ name: 'feature' }],
+                    files: [{ path: 'skills/webcmd-adapter-author/SKILL.md' }],
+                    diff: 'diff --git a/skills/webcmd-adapter-author/SKILL.md b/skills/webcmd-adapter-author/SKILL.md',
+                    url: 'https://github.com/agentrhq/webcmd/pull/42',
+                },
+            ],
+        };
+        const prompt = buildReleaseNotesPrompt(context);
+        expect(prompt).toContain('This is a major release');
+        expect(prompt).toContain('# webcmd v0.3.0: <Elegant Release Title>');
+        expect(prompt).toContain('grand enough to feel memorable, but polished rather than loud');
+    });
 });

package/dist/src/root-command-surface.d.ts

@@ -0,0 +1,31 @@
+import { Command } from 'commander';
+export declare const ROOT_PROFILE_FLAGS = "--profile <name>";
+export declare const ROOT_PROFILE_DESCRIPTION = "Chrome profile/context alias for browser runtime commands";
+export declare const COMPLETION_SENTINEL = "--get-completions";
+/**
+ * Configure the structural root options shared by the local and hosted CLI.
+ * Keeping this in one place makes Commander the source of truth for attached
+ * values, short-option clusters, missing values, and help/version precedence.
+ */
+export declare function configureRootCommandSurface(program: Command): Command;
+export type HostedRootCommandSurface = {
+    kind: 'help';
+    exitCode: number;
+} | {
+    kind: 'version';
+    output: string;
+} | {
+    kind: 'completion';
+    argv: string[];
+} | {
+    kind: 'dispatch';
+    argv: string[];
+    profile?: string;
+    literal: boolean;
+};
+/**
+ * Parse only the root command surface without registering or discovering local
+ * commands. The completion/version checks reproduce the entry-point fast paths
+ * in main.ts; all remaining root grammar is delegated to Commander itself.
+ */
+export declare function parseHostedRootCommandSurface(argv: readonly string[]): HostedRootCommandSurface;

package/dist/src/root-command-surface.js

@@ -0,0 +1,106 @@
+import { Command, CommanderError } from 'commander';
+import { CommanderStructuralError } from './command-surface.js';
+import { PKG_VERSION } from './version.js';
+export const ROOT_PROFILE_FLAGS = '--profile <name>';
+export const ROOT_PROFILE_DESCRIPTION = 'Chrome profile/context alias for browser runtime commands';
+export const COMPLETION_SENTINEL = '--get-completions';
+/**
+ * Configure the structural root options shared by the local and hosted CLI.
+ * Keeping this in one place makes Commander the source of truth for attached
+ * values, short-option clusters, missing values, and help/version precedence.
+ */
+export function configureRootCommandSurface(program) {
+    return program
+        .version(PKG_VERSION)
+        .option(ROOT_PROFILE_FLAGS, ROOT_PROFILE_DESCRIPTION)
+        .enablePositionalOptions();
+}
+/**
+ * Parse only the root command surface without registering or discovering local
+ * commands. The completion/version checks reproduce the entry-point fast paths
+ * in main.ts; all remaining root grammar is delegated to Commander itself.
+ */
+export function parseHostedRootCommandSurface(argv) {
+    const input = [...argv];
+    // main.ts checks an exact first-token version before its completion scan.
+    if (input[0] === '--version' || input[0] === '-V') {
+        return { kind: 'version', output: `${PKG_VERSION}\n` };
+    }
+    // The local completion path scans the complete raw argv before discovery or
+    // Commander parsing, including after `--` and malformed root options.
+    if (input.includes(COMPLETION_SENTINEL)) {
+        return { kind: 'completion', argv: input };
+    }
+    let stdout = '';
+    let stderr = '';
+    const boundary = findRootCommandBoundary(input);
+    const root = configureRootCommandSurface(new Command('webcmd'))
+        .exitOverride()
+        .configureOutput({
+        writeOut: value => { stdout += value; },
+        writeErr: value => { stderr += value; },
+    });
+    if (boundary.commandIndex !== undefined) {
+        // Register only the token Commander needs in order to stop root option
+        // parsing. This is structural scaffolding, not adapter discovery.
+        root.command(input[boundary.commandIndex])
+            .helpOption(false)
+            .allowUnknownOption(true)
+            .allowExcessArguments(true)
+            .argument('[commandArgs...]')
+            .exitOverride()
+            .configureOutput({ writeOut: () => undefined, writeErr: () => undefined });
+    }
+    const structuralArgv = boundary.commandIndex !== undefined
+        ? input
+        : boundary.separatorIndex !== undefined
+            ? input.slice(0, boundary.separatorIndex + 1)
+            : input;
+    try {
+        root.parse(structuralArgv, { from: 'user' });
+    }
+    catch (error) {
+        if (!(error instanceof CommanderError))
+            throw error;
+        if (error.code === 'commander.helpDisplayed')
+            return { kind: 'help', exitCode: error.exitCode };
+        if (error.code === 'commander.version') {
+            return { kind: 'version', output: stdout || `${PKG_VERSION}\n` };
+        }
+        throw new CommanderStructuralError(stderr || `${error.message}\n`, error.exitCode);
+    }
+    const profile = root.opts().profile;
+    if (boundary.commandIndex === undefined && boundary.separatorIndex === undefined)
+        return { kind: 'help', exitCode: 1 };
+    const literal = boundary.separatorIndex !== undefined;
+    const parsedArgv = boundary.commandIndex !== undefined
+        ? input.slice(boundary.commandIndex)
+        : input.slice(boundary.separatorIndex + 1);
+    if (parsedArgv.length === 0)
+        return { kind: 'help', exitCode: 1 };
+    return {
+        kind: 'dispatch',
+        argv: parsedArgv,
+        ...(profile !== undefined ? { profile } : {}),
+        literal,
+    };
+}
+/** Locates the undiscovered command token while respecting root value options. */
+function findRootCommandBoundary(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === '--profile') {
+            // Commander requires and consumes the next token even when it is `--` or
+            // starts with a dash. Structural failures have already been reported.
+            index += 1;
+            continue;
+        }
+        if (token.startsWith('--profile='))
+            continue;
+        if (token === '--')
+            return { separatorIndex: index };
+        if (!token.startsWith('-') || token === '-')
+            return { commandIndex: index };
+    }
+    return {};
+}

package/dist/src/serialization.d.ts

@@ -18,22 +18,7 @@ export type SerializedArg = {
 /** Stable arg schema — every field is always present (no sparse objects). */
 export declare function serializeArg(a: Arg): SerializedArg;
 /** Full command metadata for structured output (json/yaml). */
-export declare function serializeCommand(cmd: CliCommand): {
-    command: string;
-    site: string;
-    name: string;
-    aliases: string[];
-    description: string;
-    access: import("./registry.js").CommandAccess;
-    strategy: string;
-    browser: boolean;
-    args: SerializedArg[];
-    columns: string[];
-    domain: string | null;
-    example: string;
-    defaultFormat: "table" | "plain" | "json" | "yaml" | "yml" | "md" | "markdown" | "csv" | null;
-    siteSession: import("./registry.js").SiteSessionMode | null;
-};
+export declare function serializeCommand(cmd: CliCommand): Record<string, unknown>;
 /** Human-readable arg summary: `<required> [optional]` style. */
 export declare function formatArgSummary(args: Arg[]): string;
 /** Agent-facing canonical invocation. Adapter authors may override with `example`. */