@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

package/assets/templates/pages/table-tree/template.doc.mjs

@@ -0,0 +1,12 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'page',
+  name: 'Tree Table',
+  displayName: 'Tree Table',
+  description:
+    'Hierarchical table where every parent row rolls up from its children — a code repository whose folders show the newest commit beneath them, beside a detail sidebar and a rendered README. Columns resize, siblings sort within their own level, arrow keys walk the rows, and search prunes the tree to matching branches. Tree, hierarchy, nested rows, drilldown, expand, collapse, resizable, expandable, file browser, repository, rolled-up parents.',
+  isReady: true,
+  category: 'Table - Tree/Hierarchical List',
+};

package/assets/templates/themes/butter/butterTheme.doc.mjs

@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {
+  type: 'theme',
+  name: 'butter',
+  displayName: 'Butter',
+  description:
+    'Warm, creamy yellows with a friendly blue accent. Playful enough for consumer surfaces, soft enough to stay readable.',
+  maintained: false,
+};

package/assets/templates/themes/chocolate/chocolateTheme.doc.mjs

@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {
+  type: 'theme',
+  name: 'chocolate',
+  displayName: 'Chocolate',
+  description:
+    'Warm chocolate theme for Astryx — rich brown palette with Fraunces headings, Albert Sans body, and Lucide icons',
+  maintained: false,
+};

package/assets/templates/themes/gothic/gothicTheme.doc.mjs

@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {
+  type: 'theme',
+  name: 'gothic',
+  displayName: 'Gothic',
+  description:
+    'Deep blue-grays and a signature display serif. Dramatic and editorial, for surfaces that want to be remembered.',
+  maintained: false,
+};

package/assets/templates/themes/matcha/matchaTheme.doc.mjs

@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {
+  type: 'theme',
+  name: 'matcha',
+  displayName: 'Matcha',
+  description:
+    'Earthy greens with a calm, organic feel. Naturalistic and grounded, great for wellness or content-first apps.',
+  maintained: false,
+};

package/assets/templates/themes/neutral/neutralTheme.doc.mjs

@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {
+  type: 'theme',
+  name: 'neutral',
+  displayName: 'Neutral',
+  description:
+    'Restrained warm grays. Minimal and quiet, so the content stays the focus.',
+  maintained: true,
+};

package/assets/templates/themes/stone/stoneTheme.doc.mjs

@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {
+  type: 'theme',
+  name: 'stone',
+  displayName: 'Stone',
+  description:
+    'Warm stone and slate, earthy and understated, with just enough character to feel handcrafted.',
+  maintained: false,
+};

package/assets/templates/themes/y2k/y2kTheme.doc.mjs

@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {
+  type: 'theme',
+  name: 'y2k',
+  displayName: 'Y2K',
+  description:
+    'Hot pinks, lime greens, and Poppins. Bubbly, playful, and unmistakably retro.',
+  maintained: false,
+};

package/authoring/_shared/contract.ts

@@ -28,5 +28,27 @@ export type MutuallyAssignable<A, B> = [A] extends [B]
     : false
   : false;
 
+/**
+ * `T` without string or number index signatures, at every depth. A
+ * `.passthrough()` schema infers one and a hand-written interface never has
+ * one, so a lock drops them before comparing named fields. Recursive fields
+ * that a schema casts to their public type compare equal by construction.
+ */
+export type NamedFields<T> = T extends readonly (infer U)[]
+  ? NamedFields<U>[]
+  : T extends (...args: never[]) => unknown
+    ? T
+    : T extends object
+      ? {
+          [
+            K in keyof T as string extends K
+              ? never
+              : number extends K
+                ? never
+                : K
+          ]: NamedFields<T[K]>;
+        }
+      : T;
+
 /** Compiles only when `T` is exactly `true`; otherwise a type error. */
 export type Expect<T extends true> = T;

package/authoring/codemod/codemod.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'schema',
   name: 'codemod',
   displayName: 'Astryx Codemod',
-  namespace: 'cli',
+  namespace: 'authoring',
   description:
     'A codemod module the CLI runs during `astryx upgrade`. Default-export a ' +
     "plain object with a `type` discriminant: 'code' rewrites source files, " +
@@ -63,11 +63,13 @@ export const doc = {
               name: 'file.path',
               type: 'string',
               description: 'Absolute path to the file being transformed.',
+              required: true,
             },
             {
               name: 'file.source',
               type: 'string',
               description: 'The current source contents of the file.',
+              required: true,
             },
           ],
         },
@@ -81,18 +83,21 @@ export const doc = {
               type: 'unknown',
               description:
                 'A jscodeshift instance configured with a parser for the file.',
+              required: true,
             },
             {
               name: 'api.stats',
               type: '(...args: unknown[]) => void',
               description:
                 'Report a statistic (no-op-friendly; provided for jscodeshift parity).',
+              required: true,
             },
             {
               name: 'api.report',
               type: '(...args: unknown[]) => void',
               description:
                 'Report progress (no-op-friendly; provided for jscodeshift parity).',
+              required: true,
             },
           ],
         },
@@ -100,7 +105,7 @@ export const doc = {
     },
     {
       name: 'type',
-      type: "'code'",
+      type: "'code' | 'config'",
       description:
         "Discriminant for the file-transforming variant. Use 'config' for a " +
         'codemod that rewrites astryx.config.* instead (see notes).',

package/authoring/codemod/parse.d.mts

@@ -5,8 +5,8 @@
  * Compile-time drift-lock: sealed envelope must infer exactly the public
  * stamped-codemod union.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').Equal<
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').Equal<
  *     z.infer<typeof codemodEnvelopeSchema>,
  *     AstryxCodemod | AstryxConfigCodemod
  *   >
@@ -24,10 +24,10 @@ export function parseCodemod(input: unknown, label?: string): AstryxCodemod | As
  * Compile-time drift-lock: sealed envelope must infer exactly the public
  * stamped-codemod union.
  */
-export type _CodemodDriftLock = import("../_shared/contract").Expect<import("../_shared/contract").Equal<z.infer<typeof codemodEnvelopeSchema>, AstryxCodemod | AstryxConfigCodemod>>;
-export type AstryxCodemod = import("./type").AstryxCodemod;
-export type AstryxConfigCodemod = import("./type").AstryxConfigCodemod;
-export type AstryxCodemodTransform = import("./type").AstryxCodemodTransform;
+export type _CodemodDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").Equal<z.infer<typeof codemodEnvelopeSchema>, AstryxCodemod | AstryxConfigCodemod>>;
+export type AstryxCodemod = import("./type.js").AstryxCodemod;
+export type AstryxConfigCodemod = import("./type.js").AstryxConfigCodemod;
+export type AstryxCodemodTransform = import("./type.js").AstryxCodemodTransform;
 import { z } from 'zod';
 /**
  * The load-boundary contract: a stamped codemod default export, discriminated
@@ -38,13 +38,13 @@ declare const codemodEnvelopeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     isOptional: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     fileExtensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    transform: z.ZodType<import("./type").AstryxCodemodTransform, any, z.core.$ZodTypeInternals<import("./type").AstryxCodemodTransform, any>>;
+    transform: z.ZodType<import("./type.js").AstryxCodemodTransform, any, z.core.$ZodTypeInternals<import("./type.js").AstryxCodemodTransform, any>>;
     type: z.ZodLiteral<"code">;
 }, z.core.$strict>, z.ZodObject<{
     title: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     isOptional: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    transform: z.ZodType<import("./type").AstryxCodemodTransform, any, z.core.$ZodTypeInternals<import("./type").AstryxCodemodTransform, any>>;
+    transform: z.ZodType<import("./type.js").AstryxCodemodTransform, any, z.core.$ZodTypeInternals<import("./type.js").AstryxCodemodTransform, any>>;
     type: z.ZodLiteral<"config">;
 }, z.core.$strict>], "type">;
 export {};

package/authoring/codemod/parse.mjs

@@ -10,12 +10,14 @@
 import {z} from 'zod';
 import {formatZodError} from '../_shared/errors.mjs';
 
-/** @typedef {import('./type').AstryxCodemod} AstryxCodemod */
-/** @typedef {import('./type').AstryxConfigCodemod} AstryxConfigCodemod */
-/** @typedef {import('./type').AstryxCodemodTransform} AstryxCodemodTransform */
+/** @typedef {import('./type.js').AstryxCodemod} AstryxCodemod */
+/** @typedef {import('./type.js').AstryxConfigCodemod} AstryxConfigCodemod */
+/** @typedef {import('./type.js').AstryxCodemodTransform} AstryxCodemodTransform */
 
 const transform = /** @type {z.ZodType<AstryxCodemodTransform>} */ (
-  z.custom(value => typeof value === 'function', {message: 'Expected a function'})
+  z.custom(value => typeof value === 'function', {
+    message: 'Expected a function',
+  })
 );
 
 const codeCodemodSchema = z
@@ -52,8 +54,8 @@ const codemodEnvelopeSchema = z.discriminatedUnion('type', [
  * Compile-time drift-lock: sealed envelope must infer exactly the public
  * stamped-codemod union.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').Equal<
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').Equal<
  *     z.infer<typeof codemodEnvelopeSchema>,
  *     AstryxCodemod | AstryxConfigCodemod
  *   >

package/authoring/codemod/type.ts

@@ -128,7 +128,19 @@ export interface CodemodEntry {
 /** The result of running a single codemod over one or more files. */
 export interface CodemodRunResult {
   filesChanged: number;
+  /** Existing owned files changed or previewed by this codemod. */
+  changedFiles: string[];
+  /** Files actually written; empty during a dry run. */
   writtenFiles: string[];
+  /** Existing files that require the change but are protected. */
+  protectedFiles: Array<{
+    file: string;
+    codemod: string;
+    reason: string;
+    declaration: string;
+    generated: boolean;
+    command?: string;
+  }>;
   errors: Array<{file: string; codemod: string; error: string}>;
 }
 

package/authoring/config/config.doc.mjs

@@ -10,8 +10,8 @@
 export const doc = {
   type: 'schema',
   name: 'config',
-  displayName: 'Astryx Config',
-  namespace: 'cli',
+  displayName: 'astryx.config',
+  namespace: 'authoring',
   description:
     'The optional astryx.config.* file at your project root. Declares which ' +
     'integrations to load, where to route issue links, post-codemod hooks, local ' +
@@ -48,7 +48,7 @@ export const doc = {
       name: 'debug',
       type: '(event: DebugEvent) => void',
       description:
-        'Record every command run. The handler is synchronous; promises are not awaited and output goes to stderr. Declare `debug` directly in this file so early commands can discover it. An integration can supply one too, as a `debug` named export from its manifest — both run; set `{"astryx": {"inheritDebug": false}}` in package.json to take only your own.',
+        'Record every command run. The handler is synchronous; promises are not awaited and output goes to stderr. Declare `debug` directly in this file so early commands can discover it. An integration can supply one too, as a `debug` named export from its manifest. Every handler runs: yours first, then each integration\'s in load order (the `integrations` list, then autolinked ones). A handler that throws is skipped; the others still run and the command\'s result does not change. Set `{"astryx": {"inheritDebug": false}}` in package.json to take only your own.',
       example:
         "event => appendFileSync('runs.ndjson', JSON.stringify(event) + '\\n')",
     },
@@ -60,6 +60,14 @@ export const doc = {
       example:
         "{ audience: 'internal', async handle(report, {signal}) { return sendGap(report, {signal}); } }",
     },
+    {
+      name: 'discover',
+      type: 'DiscoverSource',
+      description:
+        'Tell `astryx discover` which integrations this project could add: an async function that returns a catalog. An integration can provide one too, as a `discover` named export from its manifest. Discover calls every source, yours first, and one that fails never hides the others. Discover only reads; your package manager installs.',
+      example:
+        "async ({signal, package: name, version}) => fetchCatalog({signal, name, version})",
+    },
     {
       name: 'experimental',
       type: '{ xle?: { components?: Record<string, XleComponent> } }',

package/authoring/config/debug-composition.test.mjs

@@ -0,0 +1,92 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `debug` accepts handlers from integrations, so both public entries for
+ * it — the exported `AstryxConfig` type and `astryx docs authoring config` —
+ * must state how those handlers combine with the app's own: the contribution
+ * form, the order, what a failing handler does, and the refusal control.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import ts from 'typescript';
+import {describe, expect, it} from 'vitest';
+import {doc} from './config.doc.mjs';
+
+const TYPE_FILE = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  'type.ts',
+);
+const source = ts.createSourceFile(
+  TYPE_FILE,
+  fs.readFileSync(TYPE_FILE, 'utf8'),
+  ts.ScriptTarget.Latest,
+  true,
+);
+
+/** @param {ts.Node} node @returns {string} */
+function jsdocText(node) {
+  return ts
+    .getJSDocCommentsAndTags(node)
+    .map(jsdoc => ts.getTextOfJSDocComment(jsdoc.comment) ?? '')
+    .join('\n');
+}
+
+/** @param {(node: ts.Node) => boolean} match @returns {ts.Node} */
+function findTopLevel(match) {
+  const node = source.statements.find(match);
+  if (!node) throw new Error('declaration not found in config/type.ts');
+  return node;
+}
+
+const configInterface = /** @type {ts.InterfaceDeclaration} */ (
+  findTopLevel(
+    node => ts.isInterfaceDeclaration(node) && node.name.text === 'AstryxConfig',
+  )
+);
+const debugMember = configInterface.members.find(
+  member =>
+    ts.isPropertySignature(member) && member.name.getText(source) === 'debug',
+);
+if (!debugMember) throw new Error('AstryxConfig has no debug member');
+
+const debugConfigAlias = findTopLevel(
+  node => ts.isTypeAliasDeclaration(node) && node.name.text === 'DebugConfig',
+);
+
+const schemaField = doc.fields.find(field => field.name === 'debug');
+
+const ENTRIES = {
+  'the AstryxConfig type': jsdocText(debugMember),
+  'astryx docs authoring config': schemaField?.description ?? '',
+};
+
+describe.each(Object.entries(ENTRIES))('debug entry in %s', (_, text) => {
+  it('says integrations contribute, and in what form', () => {
+    expect(text).toMatch(/integration/i);
+    expect(text).toMatch(/`debug` named export/);
+  });
+
+  it('says every handler runs, the app first, then integrations in load order', () => {
+    expect(text).toMatch(/\bfirst\b/i);
+    expect(text).toMatch(/load order/i);
+  });
+
+  it('says a handler that throws is skipped without affecting the others', () => {
+    expect(text).toMatch(/throws is skipped/i);
+    expect(text).toMatch(/others still run/i);
+  });
+
+  it('names the one control that refuses inherited handlers', () => {
+    expect(text).toContain('{"astryx": {"inheritDebug": false}}');
+  });
+});
+
+describe('DebugConfig', () => {
+  it('does not claim that leaving debug out records nothing', () => {
+    const text = jsdocText(debugConfigAlias);
+    expect(text).not.toMatch(/nothing is recorded/i);
+    expect(text).toMatch(/integration/i);
+  });
+});

package/authoring/config/parse.d.mts

@@ -6,8 +6,8 @@
  * {@link AstryxConfig} type. If they drift, `Equal` becomes `false` and
  * `Expect<false>` fails the `tsconfig.authoring-contract.json` typecheck.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').MutuallyAssignable<z.infer<typeof configSchema>, AstryxConfig>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<z.infer<typeof configSchema>, AstryxConfig>
  * >} _ConfigDriftLock
  */
 /**
@@ -23,13 +23,14 @@ export function parseConfig(input: unknown, label?: string): AstryxConfig;
  * {@link AstryxConfig} type. If they drift, `Equal` becomes `false` and
  * `Expect<false>` fails the `tsconfig.authoring-contract.json` typecheck.
  */
-export type _ConfigDriftLock = import("../_shared/contract").Expect<import("../_shared/contract").MutuallyAssignable<z.infer<typeof configSchema>, AstryxConfig>>;
-export type AstryxConfig = import("./type").AstryxConfig;
-export type PostCodemodHook = import("./type").PostCodemodHook;
-export type XleComponent = import("./type").XleComponent;
-export type DebugConfig = import("./type").DebugConfig;
-export type DebugEventHandler = import("../debug/type").DebugEventHandler;
-export type GapReportHandler = import("../gap-report/type").GapReportHandler;
+export type _ConfigDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").MutuallyAssignable<z.infer<typeof configSchema>, AstryxConfig>>;
+export type AstryxConfig = import("./type.js").AstryxConfig;
+export type PostCodemodHook = import("./type.js").PostCodemodHook;
+export type XleComponent = import("./type.js").XleComponent;
+export type DebugConfig = import("./type.js").DebugConfig;
+export type DebugEventHandler = import("../debug/type.js").DebugEventHandler;
+export type GapReportHandler = import("../gap-report/type.js").GapReportHandler;
+export type DiscoverSource = import("../discover/type.js").DiscoverSource;
 import { z } from 'zod';
 declare const configSchema: z.ZodObject<{
     integrations: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -40,14 +41,15 @@ declare const configSchema: z.ZodObject<{
             buildCommand: z.ZodType<(ctx: {
                 packageDir: string;
                 files: string[];
-            }) => import("./type").PostCodemodCommand | null | undefined | Promise<import("./type").PostCodemodCommand | null | undefined>, any, z.core.$ZodTypeInternals<(ctx: {
+            }) => import("./type.js").PostCodemodCommand | null | undefined | Promise<import("./type.js").PostCodemodCommand | null | undefined>, any, z.core.$ZodTypeInternals<(ctx: {
                 packageDir: string;
                 files: string[];
-            }) => import("./type").PostCodemodCommand | null | undefined | Promise<import("./type").PostCodemodCommand | null | undefined>, any>>;
+            }) => import("./type.js").PostCodemodCommand | null | undefined | Promise<import("./type.js").PostCodemodCommand | null | undefined>, any>>;
         }, z.core.$strict>>>;
     }, z.core.$strict>>;
-    debug: z.ZodOptional<z.ZodType<import("../debug/type").DebugEventHandler, any, z.core.$ZodTypeInternals<import("../debug/type").DebugEventHandler, any>>>;
-    gapReport: z.ZodOptional<z.ZodType<import("../gap-report/type").GapReportHandler, any, z.core.$ZodTypeInternals<import("../gap-report/type").GapReportHandler, any>>>;
+    debug: z.ZodOptional<z.ZodType<import("../debug/type.js").DebugEventHandler, any, z.core.$ZodTypeInternals<import("../debug/type.js").DebugEventHandler, any>>>;
+    gapReport: z.ZodOptional<z.ZodType<import("../gap-report/type.js").GapReportHandler, any, z.core.$ZodTypeInternals<import("../gap-report/type.js").GapReportHandler, any>>>;
+    discover: z.ZodOptional<z.ZodType<import("../discover/type.js").DiscoverSource, any, z.core.$ZodTypeInternals<import("../discover/type.js").DiscoverSource, any>>>;
     experimental: z.ZodOptional<z.ZodObject<{
         xle: z.ZodOptional<z.ZodObject<{
             components: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{

package/authoring/config/parse.mjs

@@ -12,13 +12,15 @@
 import {z} from 'zod';
 import {formatZodError} from '../_shared/errors.mjs';
 import {parseGapReportHandler} from '../gap-report/parse.mjs';
+import {parseDiscoverSource} from '../discover/parse.mjs';
 
-/** @typedef {import('./type').AstryxConfig} AstryxConfig */
-/** @typedef {import('./type').PostCodemodHook} PostCodemodHook */
-/** @typedef {import('./type').XleComponent} XleComponent */
-/** @typedef {import('./type').DebugConfig} DebugConfig */
-/** @typedef {import('../debug/type').DebugEventHandler} DebugEventHandler */
-/** @typedef {import('../gap-report/type').GapReportHandler} GapReportHandler */
+/** @typedef {import('./type.js').AstryxConfig} AstryxConfig */
+/** @typedef {import('./type.js').PostCodemodHook} PostCodemodHook */
+/** @typedef {import('./type.js').XleComponent} XleComponent */
+/** @typedef {import('./type.js').DebugConfig} DebugConfig */
+/** @typedef {import('../debug/type.js').DebugEventHandler} DebugEventHandler */
+/** @typedef {import('../gap-report/type.js').GapReportHandler} GapReportHandler */
+/** @typedef {import('../discover/type.js').DiscoverSource} DiscoverSource */
 
 // Typed `z.custom` so `z.infer` reproduces the real function type (not `unknown`).
 const buildCommand = /** @type {z.ZodType<PostCodemodHook['buildCommand']>} */ (
@@ -66,6 +68,22 @@ const gapReportHandlerSchema = /** @type {z.ZodType<GapReportHandler>} */ (
   )
 );
 
+// The same check an integration's `discover` named export passes. Typed
+// z.custom preserves the public function type.
+const discoverSourceSchema = /** @type {z.ZodType<DiscoverSource>} */ (
+  z.custom(
+    value => {
+      try {
+        parseDiscoverSource(value, 'discover');
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    {message: 'Expected a discover source function'},
+  )
+);
+
 const configSchema = z
   .object({
     integrations: z.array(z.string()).optional(),
@@ -76,6 +94,7 @@ const configSchema = z
       .optional(),
     debug: debugSchema.optional(),
     gapReport: gapReportHandlerSchema.optional(),
+    discover: discoverSourceSchema.optional(),
     experimental: z
       .object({
         xle: z
@@ -95,8 +114,8 @@ const configSchema = z
  * {@link AstryxConfig} type. If they drift, `Equal` becomes `false` and
  * `Expect<false>` fails the `tsconfig.authoring-contract.json` typecheck.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').MutuallyAssignable<z.infer<typeof configSchema>, AstryxConfig>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').MutuallyAssignable<z.infer<typeof configSchema>, AstryxConfig>
  * >} _ConfigDriftLock
  */
 

package/authoring/config/parse.test.mjs

@@ -63,6 +63,14 @@ describe('parseConfig (load boundary)', () => {
     ).toEqual({audience: 'internal', handle});
   });
 
+  it('accepts a discover source function and refuses anything else', () => {
+    const discover = async () => ({});
+    expect(parseConfig({discover}).discover).toBe(discover);
+    expect(reason({discover: 'https://example.com/catalog.json'})).toContain(
+      'discover',
+    );
+  });
+
   it('rejects obsolete or extended gap-report handler shapes', () => {
     expect(reason({gapReport: {command: './report.mjs'}})).toContain(
       'gapReport',

package/authoring/config/type.ts

@@ -9,8 +9,9 @@
  * boundary; there is no factory to call.
  */
 
-import type {DebugEventHandler} from '../debug/type';
-import type {GapReportHandler} from '../gap-report/type';
+import type {DebugEventHandler} from '../debug/type.js';
+import type {GapReportHandler} from '../gap-report/type.js';
+import type {DiscoverSource} from '../discover/type.js';
 
 /**
  * A command to run as part of a post-codemod hook. Returned by a hook's
@@ -21,7 +22,7 @@ export interface PostCodemodCommand {
   args?: string[];
   options?: {
     cwd?: string;
-    env?: NodeJS.ProcessEnv;
+    env?: Record<string, string | undefined>;
     timeout?: number;
   };
 }
@@ -56,8 +57,9 @@ export interface XleComponent {
 /**
  * Record every astryx command run in this project.
  *
- * A function that receives each run. Setting it is the whole opt-in; leave it
- * out and nothing is recorded.
+ * A function that receives each run. Leaving it out does not stop a handler an
+ * integration contributes; see {@link AstryxConfig.debug} for how the two
+ * combine and how to refuse inherited handlers.
  *
  * ```
  * export default {
@@ -80,10 +82,31 @@ export interface AstryxConfig {
   hooks?: {
     postCodemod?: PostCodemodHook[];
   };
-  /** Record every astryx command run in this project. See {@link DebugConfig}. */
+  /**
+   * Record every astryx command run in this project. See {@link DebugConfig}.
+   *
+   * An integration can contribute a handler too, as a `debug` named export
+   * from its `astryx.integration.*` module. Every handler receives the run:
+   * this one first, then each integration's in load order (the ones
+   * `integrations` lists, in that order, then autolinked ones). A handler that
+   * throws is skipped; the others still run and the command's result does not
+   * change. To refuse inherited handlers, set
+   * `{"astryx": {"inheritDebug": false}}` in the project's package.json; this
+   * handler still runs.
+   */
   debug?: DebugConfig;
   /** Route gap reports through a project-owned handler. See {@link GapReportHandler}. */
   gapReport?: GapReportHandler;
+  /**
+   * Tell `astryx discover` about integrations this project could add. See
+   * {@link DiscoverSource}.
+   *
+   * An integration can provide a source too, as a `discover` named export from
+   * its `astryx.integration.*` module. Discover calls every source: this one
+   * first, then each integration's in load order, and one that fails never
+   * hides the others.
+   */
+  discover?: DiscoverSource;
   /**
    * EXPERIMENTAL — shape may change and is not part of the stable config
    * contract. Provisional home for features still being proven out.

package/authoring/debug/debug.doc.d.mts

@@ -0,0 +1,11 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file SchemaDoc for DebugEvent, the record of one CLI run.
+ * @input The DebugEvent type beside it (`type.ts`), which `parse.mjs` reads.
+ * @output The `debug-event` section of `astryx docs authoring`.
+ * @position packages/cli/authoring/debug — schema documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;