An open source design system that's fully customizable and agent ready
TypeScript
feat(cli): gap-report --to files a report where the person chose (#7724)
Joey6a3ff0fe16c7
diff --git a/.changeset/cli-gap-report-to.md b/.changeset/cli-gap-report-to.mdnew file mode 100644index 0000000000..a61d73e90b--- /dev/null+++ b/.changeset/cli-gap-report-to.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[feat] `astryx gap-report --to <package>` sends a report to the issues URL of the loaded integration the person chose, under the same `--confirm-public` rule, instead of the default handlers. When loaded integrations name their own issues URLs, `--list-categories` and the receipt list every destination and tell the agent to ask the person where to file. The default route is unchanged.++@josephfarinadiff --git a/packages/cli/README.md b/packages/cli/README.mdindex 5e26d1c180..4e0d665427 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -447,8 +447,8 @@ Every response has a `type` discriminant. The full set is below (generated from| `build.kit` | The template to start from and its kit: query, hasResults, matchCount (never a cap), directMatch, start {name, package, command, basis, reason, alternatives, ...} (the start and each alternative name the package that owns the template), pages (search's closest templates), blocks and domain as SearchResultEntry[] (each naming its package), frame and foundation (Core component names), and hint {reason, commands} when thin. || `swizzle.list` | The names of swizzlable components discoverable from cwd's @astryxdesign/core. The envelope's package is @astryxdesign/core. || `swizzle.copy` | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and, when the owner has an issues URL, feedback ({issuesUrl, ghCommand?}): where to report the gap that led to swizzling. The envelope's package names the same owning package. |-| `gap-report.categories` | The fixed gap category values and human-readable labels. |-| `gap-report.file` | An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project \| integration \| fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals. |+| `gap-report.categories` | The fixed gap category values and human-readable labels; when a loaded integration names its own issues URL, meta.destinations lists every destination ({to, default, issuesUrl}) and meta.ask tells an agent to ask the person. |+| `gap-report.file` | An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project \| integration \| fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals; without --to, when a loaded integration names its own issues URL, destinations and ask as on gap-report.categories. || `template.list` | The effective discovered TemplateListEntry[] for pages and blocks. A winning replacement entry includes optional `replaces`, naming the Core id omitted from the default list. || `template.show` | The resolved template's source, exactly as a copy writes it, plus its description, kind, the component names it composes, and demoMediaReplaced (how many Astryx demo media references were replaced with placeholders for you to swap for your own media). || `template.skeleton` | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes. The envelope's package names the npm package that owns the template. |diff --git a/packages/cli/api/gap-report/gap-report.doc.mjs b/packages/cli/api/gap-report/gap-report.doc.mjsindex 377d21d5ae..3786413aca 100644--- a/packages/cli/api/gap-report/gap-report.doc.mjs+++ b/packages/cli/api/gap-report/gap-report.doc.mjs@@ -19,6 +19,8 @@ export const doc = {'Sends a gap report to every configured handler: the project config handler first, then each integration handler in config order. ' +'Each handler has 30 s to finish, and its output goes to stderr. Public handlers run only with confirmPublic; internal handlers always run. ' +"With no handler, it files a GitHub issue for the owning package only with confirmPublic (without it nothing is sent), or returns the package's issues URL when that is not on GitHub. " ++ "With options.to, the report goes only to that integration's issues URL instead, under the same confirmPublic rule. " ++ 'When loaded integrations name their own issues URLs, the response lists every destination with a line telling an agent to ask the person where to file; pass their choice as options.to, never a package the agent picked itself. ' +'The report records whether an agent or a person ran it, and the response lists each handler outcome in order.',importPath: '@astryxdesign/cli/api',signature:@@ -67,14 +69,20 @@ export const doc = {name: 'options.confirmPublic',type: 'boolean',description:- 'Allow public delivery: public handlers run, and with no handler a GitHub issue is filed through the gh CLI.',+ 'Allow public delivery: public handlers run, and a GitHub issues URL gets an issue filed through the gh CLI.',default: 'false',},+ {+ name: 'options.to',+ type: 'string',+ description:+ 'A destination the person chose: a loaded integration whose manifest names an issues URL. The report goes only to that issues URL; handlers do not run.',+ },{name: 'options.listCategories',type: 'boolean',description:- 'Return categories without resolving a route or writing; the component and every other option are refused with ERR_INVALID_ARGUMENT.',+ 'Return categories, and the destinations in meta when there is more than one, without resolving a route or writing; the component and every other option are refused with ERR_INVALID_ARGUMENT.',default: 'false',},{@@ -115,7 +123,7 @@ export const doc = {},{code: 'ERR_UNKNOWN_PACKAGE',- when: 'the explicitly selected package is not loaded',+ when: 'the explicitly selected package is not loaded, or options.to names no destination (the error lists the destinations)',},{code: 'ERR_NOT_FOUND',diff --git a/packages/cli/api/gap-report/gap-report.mjs b/packages/cli/api/gap-report/gap-report.mjsindex d85b8a3793..b4e4b02c08 100644--- a/packages/cli/api/gap-report/gap-report.mjs+++ b/packages/cli/api/gap-report/gap-report.mjs@@ -55,6 +55,14 @@ export const GAP_REPORT_CATEGORIES = Object.freeze([export const PUBLIC_CONFIRMATION_MESSAGE ='Rerun with --confirm-public to file this report.';+/** What an agent does when more than one destination exists. */+export const ASK_DESTINATION_MESSAGE =+ 'Ask the person where to file this report, then pass their choice with --to <package>. Never pick a package destination yourself; leave --to out to use the default.';++/**+ * @typedef {import('./gap-report.type.mjs').GapReportDestination} GapReportDestination+ */+/*** @typedef {object} ReportTarget* @property {string} package@@ -537,15 +545,14 @@ function githubRoute(issuesUrl) {}/**- * Built-in GitHub fallback — runs only when the effective handler set is empty.- * Requires confirmPublic.+ * File a report on GitHub with `gh` — for the zero-handler fallback and for a+ * destination the caller names. Requires confirmPublic.*- * @param {ReportTarget} target* @param {{component: string, categoryLabel: string, intention: string, detail?: string, source: string, timestamp: string}} report* @param {{repo: string}} github* @returns {Promise<Pick<import('./gap-report.type.mjs').GapReportDelivery, 'status'|'url'|'message'>>}*/-async function runGithubFallback(target, report, github) {+async function runGithubFallback(report, github) {const {execFile} = await import('node:child_process');const title = `[gap] ${report.component}: ${report.intention.slice(0, 70)}`;const body = [@@ -607,6 +614,87 @@ async function runGithubFallback(target, report, github) {}}+/**+ * Send a report to an issues URL: a GitHub issues URL is filed with `gh` only+ * with consent; any other URL comes back as routed_only. Serves the+ * zero-handler fallback (spec:AST-031/FR8) and a destination named with `to`+ * (architecture:cli-surface INV36).+ *+ * @param {string} issuesUrl+ * @param {{component: string, categoryLabel: string, intention: string, detail?: string, source: string, timestamp: string}} report+ * @param {boolean} confirmPublic+ * @returns {Promise<import('./gap-report.type.mjs').GapReportDelivery>}+ */+async function deliverToIssuesUrl(issuesUrl, report, confirmPublic) {+ const github = githubRoute(issuesUrl);+ if (github != null && !confirmPublic) {+ return {+ handlerType: 'fallback',+ handler: 'github',+ audience: 'public',+ status: 'consent_required',+ url: null,+ message: PUBLIC_CONFIRMATION_MESSAGE,+ };+ }+ if (github) {+ return {+ handlerType: 'fallback',+ handler: 'github',+ audience: 'public',+ ...(await runGithubFallback(report, github)),+ };+ }+ return {+ handlerType: 'fallback',+ handler: 'issuesUrl',+ audience: null,+ status: 'routed_only',+ url: issuesUrl,+ message:+ 'No automatic handler is available; open the routed URL to file this report.',+ };+}++/**+ * Where a report can go: the default (the handlers, or with none the owning+ * package's issues URL), then each loaded integration that names its own+ * issues URL (architecture:cli-surface INV36).+ *+ * @param {Project} project+ * @returns {GapReportDestination[]}+ */+function listDestinations(project) {+ /** @type {GapReportDestination[]} */+ const destinations = [{to: null, default: true, issuesUrl: null}];+ for (const integration of project.loadedIntegrations) {+ if (integration.__loadError || !integration.issuesUrl) continue;+ if (destinations.some(destination => destination.to === integration.name))+ continue;+ destinations.push({+ to: integration.name,+ default: false,+ issuesUrl: integration.issuesUrl,+ });+ }+ return destinations;+}++/**+ * The destinations of the project at `cwd`, or only the default when no+ * project loads there.+ * @param {string|undefined} cwd+ * @returns {Promise<GapReportDestination[]>}+ */+async function destinationsAt(cwd) {+ try {+ const {resolve} = await import('node:path');+ return listDestinations(await Project.load(resolve(cwd ?? process.cwd())));+ } catch {+ return [{to: null, default: true, issuesUrl: null}];+ }+}+/*** Compute the aggregate status from the deliveries.* @param {import('./gap-report.type.mjs').GapReportDelivery[]} deliveries@@ -665,6 +753,7 @@ export async function gapReport(component, options = {}) {options.detail ? '--additional-context' : null,options.package ? '--package' : null,options.confirmPublic ? '--confirm-public' : null,+ options.to != null ? '--to' : null,].filter(Boolean);if (ignored.length > 0) {throw new AstryxError(@@ -673,9 +762,13 @@ export async function gapReport(component, options = {}) {ERROR_CODES.ERR_INVALID_ARGUMENT,);}+ const destinations = await destinationsAt(options.cwd);return {type: 'gap-report.categories',data: GAP_REPORT_CATEGORIES.map(category => ({...category})),+ ...(destinations.length > 1+ ? {meta: {destinations, ask: ASK_DESTINATION_MESSAGE}}+ : {}),};}@@ -704,7 +797,33 @@ export async function gapReport(component, options = {}) {options.package,);- const entries = collectGapReportHandlers(project);+ const destinations = listDestinations(project);+ /** @type {GapReportDestination | undefined} */+ let chosen;+ // `to: null` is absent, like `package: null`; any other value is matched+ // against the destinations as given, so an empty or unknown one lists them.+ if (options.to != null) {+ const to = options.to;+ chosen = destinations.find(+ destination => !destination.default && destination.to === to,+ );+ if (!chosen) {+ const choices = destinations.filter(destination => !destination.default);+ const named = JSON.stringify(String(to).slice(0, 214));+ throw new AstryxError(+ choices.length > 0+ ? `No gap-report destination ${named}. Choose one of: ${choices.map(destination => destination.to).join(', ')}; or leave out --to for the default.`+ : `No gap-report destination ${named}: no loaded integration names an issues URL. Leave out --to for the default.`,+ choices.map(destination => ({+ name: /** @type {string} */ (destination.to),+ reason: /** @type {string} */ (destination.issuesUrl),+ })),+ ERROR_CODES.ERR_UNKNOWN_PACKAGE,+ );+ }+ }++ const entries = chosen ? [] : collectGapReportHandlers(project);const timestamp = new Date().toISOString();const source = captureEnv().invocationSource;@@ -731,8 +850,24 @@ export async function gapReport(component, options = {}) {/** @type {import('./gap-report.type.mjs').GapReportDelivery[]} */const deliveries = [];+ const routeReport = {+ component: resolvedComponent,+ categoryLabel: categoryEntry.label,+ intention,+ detail,+ source,+ timestamp,+ };- if (entries.length > 0) {+ if (chosen) {+ deliveries.push(+ await deliverToIssuesUrl(+ /** @type {string} */ (chosen.issuesUrl),+ routeReport,+ options.confirmPublic === true,+ ),+ );+ } else if (entries.length > 0) {deliveries.push(...(await deliverGapReportHandlers(entries, report, {confirmPublic: options.confirmPublic === true,@@ -746,47 +881,13 @@ export async function gapReport(component, options = {}) {ERROR_CODES.ERR_NOT_FOUND,);}-- const github = githubRoute(target.issuesUrl);- if (github != null && options.confirmPublic !== true) {- deliveries.push({- handlerType: 'fallback',- handler: 'github',- audience: 'public',- status: 'consent_required',- url: null,- message: PUBLIC_CONFIRMATION_MESSAGE,- });- } else if (github) {- const outcome = await runGithubFallback(- target,- {- component: resolvedComponent,- categoryLabel: categoryEntry.label,- intention,- detail,- source,- timestamp,- },- github,- );- deliveries.push({- handlerType: 'fallback',- handler: 'github',- audience: 'public',- ...outcome,- });- } else {- deliveries.push({- handlerType: 'fallback',- handler: 'issuesUrl',- audience: null,- status: 'routed_only',- url: target.issuesUrl,- message:- 'No automatic handler is available; open the routed URL to file this report.',- });- }+ deliveries.push(+ await deliverToIssuesUrl(+ target.issuesUrl,+ routeReport,+ options.confirmPublic === true,+ ),+ );}const filedCount = deliveries.filter(d => d.status === 'filed').length;@@ -800,10 +901,13 @@ export async function gapReport(component, options = {}) {data: {status,package: target.package,- issuesUrl: target.issuesUrl,+ issuesUrl: chosen ? chosen.issuesUrl : target.issuesUrl,deliveries,filedCount,routedOnlyCount,+ ...(!chosen && destinations.length > 1+ ? {destinations, ask: ASK_DESTINATION_MESSAGE}+ : {}),},};}diff --git a/packages/cli/api/gap-report/gap-report.test.mjs b/packages/cli/api/gap-report/gap-report.test.mjsindex f6e3dbffc6..8bf6ca2d59 100644--- a/packages/cli/api/gap-report/gap-report.test.mjs+++ b/packages/cli/api/gap-report/gap-report.test.mjs@@ -7,6 +7,7 @@ import * as path from 'node:path';import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';import {Project} from '../../foundation/config/project.mjs';import {+ ASK_DESTINATION_MESSAGE,GAP_REPORT_CATEGORIES,PUBLIC_CONFIRMATION_MESSAGE,collectGapReportHandlers,@@ -1022,6 +1023,238 @@ console.log('https://github.com/acme/widgets/issues/42');});});+describe('gapReport destinations and --to', () => {+ /** A shared internal handler that records each call in a marker file. */+ function addSharedHandler() {+ const marker = path.join(projectDir, 'shared-called');+ addIntegration({+ name: '@test/shared',+ audience: 'internal',+ handleBody: `(await import('node:fs')).writeFileSync(${JSON.stringify(marker)}, 'x'); return {status: 'filed', message: 'shared'};`,+ });+ return marker;+ }++ function addWidgets(issuesUrl = 'https://github.com/acme/widgets/issues') {+ addIntegration({name: '@test/widgets', handler: false, issuesUrl});+ }++ it('keeps the default route and lists the destinations with the ask line', async () => {+ const marker = addSharedHandler();+ addWidgets();+ configure(['@test/shared', '@test/widgets']);+ const argsFile = stubGh();++ const result = await gapReport('General', {+ ...reportOptions,+ confirmPublic: true,+ cwd: projectDir,+ });++ expect(result.data.deliveries).toEqual([+ expect.objectContaining({handler: '@test/shared', status: 'filed'}),+ ]);+ expect(fs.existsSync(marker)).toBe(true);+ expect(fs.existsSync(argsFile)).toBe(false);+ expect(result.data.destinations).toEqual([+ {to: null, default: true, issuesUrl: null},+ {+ to: '@test/widgets',+ default: false,+ issuesUrl: 'https://github.com/acme/widgets/issues',+ },+ ]);+ expect(result.data.ask).toBe(ASK_DESTINATION_MESSAGE);+ expect(ASK_DESTINATION_MESSAGE).toMatch(/ask the person/i);+ });++ it('lists no destinations when no integration names an issuesUrl', async () => {+ addSharedHandler();+ configure(['@test/shared']);++ const result = await gapReport('General', {+ ...reportOptions,+ cwd: projectDir,+ });++ expect(result.data).not.toHaveProperty('destinations');+ expect(result.data).not.toHaveProperty('ask');+ });++ it('files with the chosen integration GitHub issuesUrl only with consent, and runs no handler', async () => {+ const marker = addSharedHandler();+ addWidgets();+ configure(['@test/shared', '@test/widgets']);+ const argsFile = stubGh();++ const pending = await gapReport('General', {+ ...reportOptions,+ to: '@test/widgets',+ cwd: projectDir,+ });+ expect(pending.data.deliveries).toEqual([+ {+ handlerType: 'fallback',+ handler: 'github',+ audience: 'public',+ status: 'consent_required',+ url: null,+ message: PUBLIC_CONFIRMATION_MESSAGE,+ },+ ]);+ expect(pending.data.issuesUrl).toBe(+ 'https://github.com/acme/widgets/issues',+ );+ expect(pending.data).not.toHaveProperty('destinations');+ expect(fs.existsSync(argsFile)).toBe(false);++ const filed = await gapReport('General', {+ ...reportOptions,+ to: '@test/widgets',+ confirmPublic: true,+ cwd: projectDir,+ });+ expect(filed.data.deliveries).toHaveLength(1);+ expect(filed.data.deliveries[0]).toMatchObject({+ handlerType: 'fallback',+ handler: 'github',+ status: 'filed',+ });+ const args = JSON.parse(fs.readFileSync(argsFile, 'utf8'));+ expect(args.slice(0, 4)).toEqual([+ 'issue',+ 'create',+ '--repo',+ 'acme/widgets',+ ]);+ expect(fs.existsSync(marker)).toBe(false);+ });++ it('routes a chosen non-GitHub issuesUrl as routed_only', async () => {+ addSharedHandler();+ addWidgets('https://tracker.example/widgets');+ configure(['@test/shared', '@test/widgets']);++ const result = await gapReport('General', {+ ...reportOptions,+ to: '@test/widgets',+ cwd: projectDir,+ });++ expect(result.data.deliveries).toEqual([+ expect.objectContaining({+ handlerType: 'fallback',+ handler: 'issuesUrl',+ status: 'routed_only',+ url: 'https://tracker.example/widgets',+ }),+ ]);+ expect(result.data.status).toBe('routed_only');+ });++ it.each([+ ['a package that is not loaded', '@test/nope'],+ ['a loaded integration without an issuesUrl', '@test/shared'],+ ])(+ 'refuses --to naming %s, lists the choices, and sends nothing',+ async (_label, to) => {+ const marker = addSharedHandler();+ addWidgets();+ configure(['@test/shared', '@test/widgets']);++ await expect(+ gapReport('General', {...reportOptions, to, cwd: projectDir}),+ ).rejects.toMatchObject({+ code: 'ERR_UNKNOWN_PACKAGE',+ suggestions: [+ {+ name: '@test/widgets',+ reason: 'https://github.com/acme/widgets/issues',+ },+ ],+ });+ expect(fs.existsSync(marker)).toBe(false);+ },+ );++ it.each([+ ['an empty value', ''],+ ['a blank value', ' '],+ ['an over-long value', `@test/${'a'.repeat(300)}`],+ ])('refuses %s for --to with the destination list', async (_label, to) => {+ const marker = addSharedHandler();+ addWidgets();+ configure(['@test/shared', '@test/widgets']);++ await expect(+ gapReport('General', {...reportOptions, to, cwd: projectDir}),+ ).rejects.toMatchObject({+ code: 'ERR_UNKNOWN_PACKAGE',+ suggestions: [{name: '@test/widgets'}],+ });+ expect(fs.existsSync(marker)).toBe(false);+ });++ it('treats to: null as absent', async () => {+ const marker = addSharedHandler();+ addWidgets();+ configure(['@test/shared', '@test/widgets']);++ const result = await gapReport('General', {+ ...reportOptions,+ to: /** @type {any} */ (null),+ cwd: projectDir,+ });++ expect(result.data.deliveries).toHaveLength(1);+ expect(fs.existsSync(marker)).toBe(true);+ expect(result.data.destinations).toHaveLength(2);+ });++ it('lists the destinations with the categories', async () => {+ addSharedHandler();+ addWidgets();+ configure(['@test/shared', '@test/widgets']);++ const listed = await gapReport(undefined, {+ listCategories: true,+ cwd: projectDir,+ });++ expect(listed.data).toEqual(GAP_REPORT_CATEGORIES);+ expect(listed.meta).toEqual({+ destinations: [+ {to: null, default: true, issuesUrl: null},+ {+ to: '@test/widgets',+ default: false,+ issuesUrl: 'https://github.com/acme/widgets/issues',+ },+ ],+ ask: ASK_DESTINATION_MESSAGE,+ });+ });++ it('adds no meta to the categories when there is only the default', async () => {+ configure([]);+ const listed = await gapReport(undefined, {+ listCategories: true,+ cwd: projectDir,+ });+ expect(listed).not.toHaveProperty('meta');+ });++ it('refuses --to with --list-categories', async () => {+ await expect(+ gapReport(undefined, {+ listCategories: true,+ to: '@test/widgets',+ cwd: projectDir,+ }),+ ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});+ });+});+describe('gapReport target selection', () => {it('routes to the unique component owner', async () => {addIntegration({diff --git a/packages/cli/api/gap-report/gap-report.type.mjs b/packages/cli/api/gap-report/gap-report.type.mjsindex abca0b980c..ca549fee47 100644--- a/packages/cli/api/gap-report/gap-report.type.mjs+++ b/packages/cli/api/gap-report/gap-report.type.mjs@@ -23,12 +23,27 @@* @property {string} [package] Explicit owner package for ambiguous routes.* @property {boolean} [confirmPublic] Explicit consent for public handlers or GitHub issue creation.* @property {boolean} [listCategories] Return the category vocabulary without routing or writing.+ * @property {string} [to] A destination the person chose: a loaded integration+ * whose manifest names an issues URL. The report goes only there.+ */++/**+ * Where a report can go. The default entry (`to: null`) is the configured+ * handlers, or with none the owning package's issues URL.+ * @typedef {object} GapReportDestination+ * @property {string|null} to The value to pass as `to`; null for the default.+ * @property {boolean} default Whether this is the default destination.+ * @property {string|null} issuesUrl The integration's issues URL; null for the+ * default.*//*** @typedef {object} GapReportCategoriesResponse* @property {'gap-report.categories'} type* @property {GapReportCategoryEntry[]} data+ * @property {{destinations: GapReportDestination[], ask: string}} [meta]+ * Present when a destination besides the default exists: every destination,+ * and the line telling an agent to ask the person.*//**@@ -58,6 +73,9 @@* @property {GapReportDelivery[]} deliveries Ordered handler outcomes.* @property {number} filedCount Count of handlers that filed the report.* @property {number} routedOnlyCount Count of handlers that routed only.+ * @property {GapReportDestination[]} [destinations] For a run without `to`,+ * when a destination besides the default exists: every destination.+ * @property {string} [ask] With `destinations`: ask the person where to file.*//**diff --git a/packages/cli/assets/docs/tree/debug-and-gap-reports.doc.mjs b/packages/cli/assets/docs/tree/debug-and-gap-reports.doc.mjsindex fc1c010ac1..d78667b767 100644--- a/packages/cli/assets/docs/tree/debug-and-gap-reports.doc.mjs+++ b/packages/cli/assets/docs/tree/debug-and-gap-reports.doc.mjs@@ -167,5 +167,25 @@ message: Rerun with --confirm-public to file this report.`,},],},+ {+ id: 'choose-a-destination',+ title: 'Let the person choose where a report goes',+ content: [+ {+ type: 'prose',+ text: 'When an app loads packages that name their own `issuesUrl`, a report can go to the default (the handlers, or the fallback above) or to one of those packages. `astryx gap-report --list-categories` and the receipt of a report filed without `--to` list every destination, with a line telling the agent to ask the person.',+ },+ {+ type: 'list',+ style: 'unordered',+ items: [+ 'An agent asks the person where to file. It never picks a package destination on its own.',+ "`--to <package>` carries the person's choice: the report goes only to that package's `issuesUrl`, under the same `--confirm-public` rule, and the handlers do not run.",+ 'Without a choice, leave out `--to`; the report goes to the default.',+ 'A `--to` that names no destination fails before anything is sent and lists the destinations.',+ ],+ },+ ],+ },],};diff --git a/packages/cli/clients/cli/commands/gap-report.doc.mjs b/packages/cli/clients/cli/commands/gap-report.doc.mjsindex f18da40b14..adf4f2f2c0 100644--- a/packages/cli/clients/cli/commands/gap-report.doc.mjs+++ b/packages/cli/clients/cli/commands/gap-report.doc.mjs@@ -16,6 +16,8 @@ export const doc = {'Reports a missing component, variant, layout, styling, accessibility, API, or documentation capability to the package that owns it: the --package you name, else the integration whose component replaces it, else the one package that provides the component, else Core. ' +'Every configured handler receives the report: the project config handler first, then each integration handler in config order. Public handlers run only with --confirm-public; internal handlers always run. A failing handler does not stop the others. ' +"With no handler it files a GitHub issue for the owning package, only with --confirm-public (without it nothing is sent), or returns the package's issues URL when that is not on GitHub. " ++ "With --to <package>, the report goes only to that integration's issues URL instead, under the same --confirm-public rule. " ++ 'When loaded integrations name their own issues URLs, the output lists every destination: an agent asks the person where to file and passes their choice with --to; it never picks a package itself, and without a choice the default is used. ' +'The report records whether an agent or a person ran it.',fn: 'gapReport',args: [@@ -55,13 +57,19 @@ export const doc = {flag: '--confirm-public',param: 'options.confirmPublic',description:- 'Allow public delivery: public handlers run, and with no handler it files a GitHub issue with your gh login',+ 'Allow public delivery: public handlers run, and a GitHub issues URL gets an issue filed with your gh login',+ },+ {+ flag: '--to <package>',+ param: 'options.to',+ description:+ "Send the report only to this loaded integration's issues URL, as the person chose; the destinations the output lists are the choices",},{flag: '--list-categories',param: 'options.listCategories',description:- 'List valid report categories without filing; the component and the other gap-report options are refused with ERR_INVALID_ARGUMENT',+ 'List valid report categories, and the destinations when there is more than one, without filing; the component and the other gap-report options are refused with ERR_INVALID_ARGUMENT',},],examples: [@@ -70,6 +78,10 @@ export const doc = {label: 'Prepare a report (nothing public happens without --confirm-public)',cli: "astryx gap-report Button --category missing_variant --reason 'Need a compact size'",},+ {+ label: 'File where the person chose',+ cli: "astryx gap-report Button --category missing_variant --reason 'Need a compact size' --to @acme/widgets",+ },],exitCodes: [{diff --git a/packages/cli/clients/cli/commands/gap-report.mjs b/packages/cli/clients/cli/commands/gap-report.mjsindex 22a2a05025..05af063e4b 100644--- a/packages/cli/clients/cli/commands/gap-report.mjs+++ b/packages/cli/clients/cli/commands/gap-report.mjs@@ -7,7 +7,7 @@import {gapReport as gapReportApi} from '../../../api/gap-report/gap-report.mjs';import {NO_RESULT_SET, resultSet} from '../../../foundation/debug/index.mjs';import {jsonOut} from '../../../foundation/response/json.mjs';-import {emit, record, records, section} from '../formatters/index.mjs';+import {emit, record, records, section, text} from '../formatters/index.mjs';import {cliError} from '../lib/cli-error.mjs';import {defineCommand} from '../lib/define-command.mjs';import {doc as gapReportCommand} from './gap-report.doc.mjs';@@ -19,7 +19,7 @@ export function registerGapReport(program) {fn: gapReportFn,action: async (/** @type {string|undefined} */ component,- /** @type {{category?: string, reason?: string, additionalContext?: string, package?: string, confirmPublic?: boolean, listCategories?: boolean}} */ options,+ /** @type {{category?: string, reason?: string, additionalContext?: string, package?: string, confirmPublic?: boolean, listCategories?: boolean, to?: string}} */ options,) => {/** @type {Awaited<ReturnType<typeof gapReportApi>>} */let result;@@ -35,6 +35,7 @@ export function registerGapReport(program) {package: options.package,confirmPublic: options.confirmPublic,listCategories: options.listCategories,+ to: options.to,});} catch (error) {const err =@@ -78,6 +79,9 @@ export function registerGapReport(program) {section('Gap report categories'),records(result.data, {fields: ['value', 'label']}),);+ if (result.meta) {+ emit(...destinationBlocks(result.meta.destinations, result.meta.ask));+ }return answered;}@@ -119,8 +123,26 @@ export function registerGapReport(program) {);}+ if (result.data.destinations && result.data.ask) {+ emit(...destinationBlocks(result.data.destinations, result.data.ask));+ }+if (isFailure) process.exitCode = 1;return answered;},});}++/**+ * The destinations a report can go to, then the line telling an agent to ask+ * the person (architecture:cli-surface INV36).+ * @param {import('../../../api/gap-report/gap-report.type.mjs').GapReportDestination[]} destinations+ * @param {string} ask+ */+function destinationBlocks(destinations, ask) {+ return [+ section('Destinations'),+ records(destinations, {fields: ['to', 'default', 'issuesUrl']}),+ text(ask),+ ];+}diff --git a/packages/cli/clients/cli/commands/gap-report.test.mjs b/packages/cli/clients/cli/commands/gap-report.test.mjsindex e0f4f435b6..3b6f122799 100644--- a/packages/cli/clients/cli/commands/gap-report.test.mjs+++ b/packages/cli/clients/cli/commands/gap-report.test.mjs@@ -331,3 +331,82 @@ describe('gap-report control docs', () => {).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});});});++describe('gap-report destinations in text', () => {+ it('lists the destinations and tells the agent to ask the person', async () => {+ const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-gap-dest-'));+ try {+ fs.writeFileSync(+ path.join(cwd, 'package.json'),+ JSON.stringify({name: 'fixture-app'}),+ );+ const pkg = path.join(cwd, 'node_modules', '@test', 'widgets');+ fs.mkdirSync(pkg, {recursive: true});+ fs.writeFileSync(+ path.join(pkg, 'package.json'),+ JSON.stringify({name: '@test/widgets', version: '1.0.0'}),+ );+ fs.writeFileSync(+ path.join(pkg, 'astryx.integration.mjs'),+ "export default {issuesUrl: 'https://tracker.example/widgets'};\n",+ );+ fs.writeFileSync(+ path.join(cwd, 'astryx.config.mjs'),+ `export default {+ integrations: ['@test/widgets'],+ gapReport: {audience: 'internal', handle: () => ({status: 'filed', message: 'shared'})},+};\n`,+ );++ const listed = await runCli(['gap-report', '--list-categories'], {cwd});+ expect(listed.status).toBe(0);+ expect(listed.stdout).toContain('Destinations');+ expect(listed.stdout).toMatch(/^default:\s+true$/m);+ expect(listed.stdout).toMatch(/^to:\s+@test\/widgets$/m);+ expect(listed.stdout).toMatch(+ /^issuesUrl:\s+https:\/\/tracker\.example\/widgets$/m,+ );+ expect(listed.stdout).toMatch(/ask the person/i);++ const filed = await runCli(+ [+ 'gap-report',+ 'Button',+ '--category',+ 'docs_gap',+ '--reason',+ 'Need a keyboard example',+ ],+ {cwd},+ );+ expect(filed.status).toBe(0);+ expect(filed.stdout).toContain('Destinations');+ expect(filed.stdout).toMatch(/ask the person/i);++ const chosen = await runCli(+ [+ 'gap-report',+ 'Button',+ '--category',+ 'docs_gap',+ '--reason',+ 'Need a keyboard example',+ '--to',+ '@test/widgets',+ '--json',+ ],+ {cwd},+ );+ expect(chosen.status).toBe(0);+ expect(JSON.parse(chosen.stdout).data.deliveries).toEqual([+ expect.objectContaining({+ handler: 'issuesUrl',+ status: 'routed_only',+ url: 'https://tracker.example/widgets',+ }),+ ]);+ } finally {+ fs.rmSync(cwd, {recursive: true, force: true});+ }+ });+});diff --git a/packages/cli/foundation/response/response-types.doc.mjs b/packages/cli/foundation/response/response-types.doc.mjsindex 89fa26b7a4..d7071a167b 100644--- a/packages/cli/foundation/response/response-types.doc.mjs+++ b/packages/cli/foundation/response/response-types.doc.mjs@@ -169,12 +169,13 @@ export const doc = {// gap reports{value: 'gap-report.categories',- description: 'The fixed gap category values and human-readable labels.',+ description:+ 'The fixed gap category values and human-readable labels; when a loaded integration names its own issues URL, meta.destinations lists every destination ({to, default, issuesUrl}) and meta.ask tells an agent to ask the person.',},{value: 'gap-report.file',description:- 'An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project | integration | fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals.',+ 'An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project | integration | fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals; without --to, when a loaded integration names its own issues URL, destinations and ask as on gap-report.categories.',},// template