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

package/authoring/integration/integration.doc.mjs

@@ -11,53 +11,61 @@ export const doc = {
   type: 'schema',
   name: 'integration',
   displayName: 'Astryx Integration',
-  namespace: 'cli',
+  namespace: 'authoring',
   description:
     'The astryx.integration.* manifest that sits beside an integration ' +
-    "package's package.json. Points the CLI at the package's components, " +
-    'templates, codemods, doc topics, source themes, and managed agent guidance, ' +
-    'and where to file issues. Every field is optional.',
+    "package's package.json. It can preserve a stable provider identity across a package rename, " +
+    "and points the CLI at the package's components, templates, codemods, doc topics, " +
+    'source themes, managed agent guidance, and issue tracker. Every field is optional.',
   appliesTo: 'astryx.integration.{ts,mjs,js}',
   fields: [
+    {
+      name: 'providerId',
+      type: 'string',
+      description:
+        'The name that marks this package as the source of everything it contributes. Leave it out to use the package name from package.json. Set it to the old name only during a rename, so the IDs of what the package already contributed stay the same. If two packages use the same name here, the one you are working on wins; otherwise the one the CLI reads first wins, and the CLI warns about the other.',
+      example: "'@acme/widgets'",
+    },
     {
       name: 'components',
       type: 'string',
       description:
-        'Relative path to the components/docs root (resolved to absolute).',
+        'The folder that holds your components and their docs, relative to package.json.',
       example: "'./src/components'",
     },
     {
       name: 'templates',
       type: 'string',
       description:
-        'Relative path to the templates root (resolved to absolute).',
+        'The folder that holds your templates, relative to package.json.',
       example: "'./src/templates'",
     },
     {
       name: 'codemods',
       type: 'string',
-      description: 'Relative path to the codemods root (resolved to absolute).',
+      description:
+        'The folder that holds your codemods, relative to package.json.',
       example: "'./codemods'",
     },
     {
       name: 'docs',
       type: 'string',
       description:
-        'Relative path to the reference-docs (topics) root (resolved to absolute). Every {topic}.doc.{ts,mjs,js} under it is served by `astryx docs` beside the built-in topics; a topic may also declare `replaces` or `extends` to take the place of a built-in one or merge onto it.',
+        'The folder that holds your doc topics, relative to package.json. Every {topic}.doc.{ts,mjs,js} in it shows up in `astryx docs` next to the built-in topics; a topic can also set `replaces` or `extends` to take over a built-in topic or add to it.',
       example: "'./docs'",
     },
     {
       name: 'themes',
       type: 'string',
       description:
-        'Relative path to a source-theme catalog root containing manifest.json plus one directory per theme slug. Installed themes appear in `astryx theme list` and can be copied with `astryx theme add`.',
+        'The folder that holds your themes, relative to package.json, with one folder per theme. Each theme folder has the theme source and a matching .doc.mjs file with the same name. Installed themes show up in `astryx theme list` and can be copied with `astryx theme add`.',
       example: "'./themes'",
     },
     {
       name: 'agentDocs',
       type: '{ append?: readonly string[] }',
       description:
-        'Static package guidance appended to the end of the managed agent block. The CLI owns the section heading, package labels, bullets, target files, and writes.',
+        'Lines of guidance your package adds to the end of the agent instructions the CLI manages. The CLI owns the heading, labels, bullets, and which files it writes.',
       example: "{ append: ['Run acme verify.'] }",
     },
     {
@@ -87,9 +95,10 @@ export const doc = {
     {
       type: 'prose',
       text:
-        "Identity, the integration's name and version, comes from the " +
-        "package's package.json, not from this manifest. The manifest only " +
-        'declares where the CLI finds each kind of artifact.',
+        'The provider name defaults to the package name in package.json. ' +
+        'During a rename, set `providerId` to the old package name so the IDs ' +
+        'of what the package already contributed stay the same. The package ' +
+        'version always comes from package.json.',
     },
     {
       type: 'prose',

package/authoring/integration/parse.d.mts

@@ -1,7 +1,7 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/** @typedef {import('./type').AstryxIntegration} AstryxIntegration */
+/** @typedef {import('./type.js').AstryxIntegration} AstryxIntegration */
 /**
  * Validate an unknown value as an Astryx integration manifest, or throw.
  *
@@ -14,4 +14,4 @@
  * @returns {AstryxIntegration}
  */
 export function parseIntegration(input: unknown, label?: string): AstryxIntegration;
-export type AstryxIntegration = import("./type").AstryxIntegration;
+export type AstryxIntegration = import("./type.js").AstryxIntegration;

package/authoring/integration/parse.mjs

@@ -14,7 +14,7 @@
 import {formatZodError} from '../_shared/errors.mjs';
 import {integrationSchema} from './schema.mjs';
 
-/** @typedef {import('./type').AstryxIntegration} AstryxIntegration */
+/** @typedef {import('./type.js').AstryxIntegration} AstryxIntegration */
 
 /**
  * Validate an unknown value as an Astryx integration manifest, or throw.

package/authoring/integration/parse.test.mjs

@@ -28,6 +28,9 @@ describe('parseIntegration (load boundary)', () => {
       components: './src',
     });
     expect(parseIntegration({docs: './docs'})).toEqual({docs: './docs'});
+    expect(parseIntegration({providerId: '@acme/legacy-widgets'})).toEqual({
+      providerId: '@acme/legacy-widgets',
+    });
     expect(parseIntegration({themes: './themes'})).toEqual({
       themes: './themes',
     });
@@ -66,7 +69,9 @@ describe('parseIntegration (load boundary)', () => {
           ? 'https://example.com/issues'
           : key === 'agentDocs'
             ? {}
-            : './x',
+            : key === 'providerId'
+              ? '@acme/widgets'
+              : './x',
       ]),
     );
     expect(unknownIntegrationKeys(everyKnownKey)).toEqual([]);
@@ -82,6 +87,10 @@ describe('parseIntegration (load boundary)', () => {
     expect(reason({issuesUrl: 'nope'})).toContain('issuesUrl');
   });
 
+  it('rejects a noncanonical providerId', () => {
+    expect(reason({providerId: 'Acme Widgets'})).toContain('providerId');
+  });
+
   it('accepts an optional append array as manifest data', () => {
     expect(
       parseIntegration({

package/authoring/integration/schema.d.mts

@@ -32,6 +32,7 @@ export const agentDocsSchema: z.ZodObject<{
     append: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
 }, z.core.$strip>;
 export const integrationBaseSchema: z.ZodObject<{
+    providerId: z.ZodOptional<z.ZodString>;
     components: z.ZodOptional<z.ZodString>;
     templates: z.ZodOptional<z.ZodString>;
     codemods: z.ZodOptional<z.ZodString>;
@@ -40,6 +41,7 @@ export const integrationBaseSchema: z.ZodObject<{
     issuesUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export const integrationSchema: z.ZodObject<{
+    providerId: z.ZodOptional<z.ZodString>;
     components: z.ZodOptional<z.ZodString>;
     templates: z.ZodOptional<z.ZodString>;
     codemods: z.ZodOptional<z.ZodString>;
@@ -53,8 +55,8 @@ export const integrationSchema: z.ZodObject<{
 /**
  * Compile-time drift-lock: sealed schema must infer exactly {@link AstryxIntegration}.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').Equal<z.infer<typeof integrationSchema>, AstryxIntegration>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').Equal<z.infer<typeof integrationSchema>, AstryxIntegration>
  * >} _IntegrationDriftLock
  */
 /**
@@ -67,9 +69,9 @@ export const integrationSchema: z.ZodObject<{
  * @type {string[]}
  */
 export const KNOWN_INTEGRATION_KEYS: string[];
-export type AstryxIntegration = import("./type").AstryxIntegration;
+export type AstryxIntegration = import("./type.js").AstryxIntegration;
 /**
  * Compile-time drift-lock: sealed schema must infer exactly {@link AstryxIntegration}.
  */
-export type _IntegrationDriftLock = import("../_shared/contract").Expect<import("../_shared/contract").Equal<z.infer<typeof integrationSchema>, AstryxIntegration>>;
+export type _IntegrationDriftLock = import("../_shared/contract.js").Expect<import("../_shared/contract.js").Equal<z.infer<typeof integrationSchema>, AstryxIntegration>>;
 import { z } from 'zod';

package/authoring/integration/schema.mjs

@@ -16,11 +16,13 @@
 import {z} from 'zod';
 import {formatZodError} from '../_shared/errors.mjs';
 
-/** @typedef {import('./type').AstryxIntegration} AstryxIntegration */
+/** @typedef {import('./type.js').AstryxIntegration} AstryxIntegration */
 
 const MAX_AGENT_DOC_LINES = 8;
 const MAX_AGENT_DOC_LINE_CODE_POINTS = 240;
 const MANAGED_MARKER_TEXT = /(?:ASTRYX|XDS):(START|END)/u;
+const PROVIDER_ID_RE =
+  /^(?:@[a-z0-9][a-z0-9._~!*'()-]*\/)?[a-z0-9][a-z0-9._~!*'()-]*$/u;
 
 /**
  * @param {string} value
@@ -66,6 +68,10 @@ export const agentDocsSchema = z.object({
 });
 
 export const integrationBaseSchema = z.object({
+  providerId: z
+    .string()
+    .regex(PROVIDER_ID_RE, 'providerId must be a canonical npm package name')
+    .optional(),
   components: z.string().optional(),
   templates: z.string().optional(),
   codemods: z.string().optional(),
@@ -115,8 +121,8 @@ export function parseAgentDocsField(input, label) {
 /**
  * Compile-time drift-lock: sealed schema must infer exactly {@link AstryxIntegration}.
  *
- * @typedef {import('../_shared/contract').Expect<
- *   import('../_shared/contract').Equal<z.infer<typeof integrationSchema>, AstryxIntegration>
+ * @typedef {import('../_shared/contract.js').Expect<
+ *   import('../_shared/contract.js').Equal<z.infer<typeof integrationSchema>, AstryxIntegration>
  * >} _IntegrationDriftLock
  */
 

package/authoring/integration/type.ts

@@ -3,29 +3,40 @@
 /**
  * Public type surface for an Astryx integration manifest
  * (`astryx.integration.{ts,mjs,js}`, sibling to the integration package's
- * package.json). Identity (name/version) comes from package.json, not the
- * manifest. Authors write a plain object against {@link AstryxIntegration};
- * the CLI validates it via `parseIntegration` at the load boundary.
+ * package.json). Identity defaults to the package name, but `providerId` can keep
+ * a stable logical identity across an explicit package rename. Authors write a
+ * plain object against {@link AstryxIntegration}; the CLI validates it via
+ * `parseIntegration` at the load boundary.
  *
  * The manifest module may also carry `debug` and `gapReport` NAMED exports.
  * They are not fields here on purpose: a CLI released before a given manifest
  * field existed could reject it and lose every contribution, while an unknown
- * named export is simply not read. See the `cli-integrations` doc topic.
+ * named export is simply not read. See `astryx docs cli/integrations`.
  */
 export interface AstryxIntegration {
+  /** Stable logical provider ID. Omit to use package.json#name. Set this only
+   *  when a package rename must preserve existing artifact IDs. */
+  providerId?: string;
   /** Relative path to the components/docs root (resolved to absolute). */
   components?: string;
   /** Relative path to the templates root (resolved to absolute). */
   templates?: string;
-  /** Relative path to the codemods root (resolved to absolute). */
+  /** Relative path to the codemods root (resolved to absolute).
+   *  The root uses a version-folder-first layout:
+   *  `<codemodsRoot>/<version>/<id>.<ext>`, where `<version>` is an exact
+   *  semver string (e.g. `0.2.0`, no `v` prefix) and `<id>` is a kebab-case
+   *  module basename. Each module default-exports a codemod envelope stamped
+   *  `type: 'code'` or `type: 'config'`. Codemod ids must be unique within
+   *  a package across all versions. */
   codemods?: string;
   /** Relative path to the reference-docs (topics) root (resolved to
    *  absolute). Every `{topic}.doc.{ts,mjs,js}` under it is a topic the CLI
    *  serves from `astryx docs`, alongside the built-in ones. A topic may also
    *  `replace` or `extend` a built-in topic; see the ReferenceDoc type. */
   docs?: string;
-  /** Relative path to the source-theme catalog root (resolved to absolute).
-   *  The root contains `manifest.json` plus one directory per theme slug. */
+  /** Relative path to the source-theme root (resolved to absolute). Each
+   *  lower-kebab theme directory contains a source module and mandatory
+   *  same-stem, strongly typed `.doc.mjs` descriptor. */
   themes?: string;
   /** Static package guidance appended to the CLI-owned managed agent block. */
   agentDocs?: {
@@ -49,4 +60,4 @@ export type {
   GapReportCategory,
   GapReportTarget,
   GapReportHandlerReceipt,
-} from '../gap-report/type';
+} from '../gap-report/type.js';

package/authoring/shadcn/receipt.d.mts

@@ -63,7 +63,7 @@ export function createRegistryReceipt(input: {
         name: string;
         path: string;
         aliases: string[];
-        kind: "block" | "page" | "example" | "showcase";
+        kind: "page" | "block" | "example" | "showcase";
     };
     source: {
         package: "@astryxdesign/cli";
@@ -83,7 +83,7 @@ export function createRegistryReceipt(input: {
         name: string;
         path: string;
         aliases: string[];
-        kind: "block" | "page" | "example" | "showcase";
+        kind: "page" | "block" | "example" | "showcase";
     };
     source: {
         package: "@astryxdesign/cli";
@@ -112,7 +112,7 @@ export function parseRegistryReceipt(input: unknown): {
         name: string;
         path: string;
         aliases: string[];
-        kind: "block" | "page" | "example" | "showcase";
+        kind: "page" | "block" | "example" | "showcase";
     };
     source: {
         package: "@astryxdesign/cli";
@@ -132,7 +132,7 @@ export function parseRegistryReceipt(input: unknown): {
         name: string;
         path: string;
         aliases: string[];
-        kind: "block" | "page" | "example" | "showcase";
+        kind: "page" | "block" | "example" | "showcase";
     };
     source: {
         package: "@astryxdesign/cli";
@@ -165,8 +165,8 @@ export const registryReceiptSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         path: z.ZodString;
         aliases: z.ZodArray<z.ZodString>;
         kind: z.ZodEnum<{
-            block: "block";
             page: "page";
+            block: "block";
             example: "example";
             showcase: "showcase";
         }>;
@@ -190,8 +190,8 @@ export const registryReceiptSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         path: z.ZodString;
         aliases: z.ZodArray<z.ZodString>;
         kind: z.ZodEnum<{
-            block: "block";
             page: "page";
+            block: "block";
             example: "example";
             showcase: "showcase";
         }>;

package/clients/cli/__tests__/cliManifest.test.ts

@@ -3,37 +3,35 @@
 import fs from 'fs';
 import path from 'path';
 import {describe, it, expect} from 'vitest';
-
-describe('@astryxdesign/cli Theme Manifest & Template Validation', () => {
-  const manifestPath = path.resolve(
-    'packages/cli/assets/templates/themes/manifest.json',
-  );
-
-  it('validates theme manifest existence and structure', () => {
-    expect(fs.existsSync(manifestPath)).toBe(true);
-    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-
-    expect(manifest.version).toBe(1);
-    expect(Array.isArray(manifest.themes)).toBe(true);
-    expect(manifest.themes.length).toBeGreaterThan(0);
-  });
-
-  it('verifies all referenced theme files exist', () => {
-    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-    const themesDir = path.dirname(manifestPath);
-
-    for (const theme of manifest.themes) {
-      expect(theme.slug).toBeDefined();
-      expect(theme.displayName).toBeDefined();
-      expect(theme.entry).toBeDefined();
-
-      const entryPath = path.join(themesDir, theme.slug, theme.entry);
-      expect(fs.existsSync(entryPath)).toBe(true);
-
+import {discoverBundledThemes} from '../../../foundation/discovery/theme-discovery.mjs';
+
+describe('@astryxdesign/cli bundled theme descriptor validation', () => {
+  it('discovers typed descriptors and their same-stem source files', () => {
+    const themes = discoverBundledThemes();
+    expect(themes.length).toBeGreaterThan(0);
+
+    for (const theme of themes) {
+      expect(theme.slug).toBeTruthy();
+      expect(theme.displayName).toBeTruthy();
+      expect(theme.docPath).toBe(
+        path.join(
+          theme.sourceDir,
+          `${path.basename(theme.entry, path.extname(theme.entry))}.doc.mjs`,
+        ),
+      );
+      expect(fs.existsSync(theme.docPath)).toBe(true);
+      expect(fs.existsSync(path.join(theme.sourceDir, theme.entry))).toBe(true);
       for (const file of theme.files) {
-        const filePath = path.join(themesDir, theme.slug, file);
-        expect(fs.existsSync(filePath)).toBe(true);
+        expect(fs.existsSync(path.join(theme.sourceDir, file))).toBe(true);
       }
     }
   });
+
+  it('does not ship the obsolete central theme catalog', () => {
+    expect(
+      fs.existsSync(
+        path.resolve('packages/cli/assets/templates/themes/manifest.json'),
+      ),
+    ).toBe(false);
+  });
 });

package/clients/cli/command-load-failure.test.mjs

@@ -0,0 +1,83 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A command whose module fails to import still answers: with --json, one
+ * error envelope on stdout; without it, the error on stderr. Exit 1 either way.
+ *
+ * The failure is injected with a module-load hook in a real subprocess, so the
+ * lazy command registry in index.mjs sees what a broken install would give it.
+ */
+
+import {describe, it, expect, beforeAll, afterAll} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+
+const BIN = fileURLToPath(new URL('./bin/astryx.mjs', import.meta.url));
+
+/** @type {string} */
+let dir;
+/** @type {string} */
+let register;
+
+beforeAll(() => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-load-failure-'));
+  const hooks = path.join(dir, 'hooks.mjs');
+  fs.writeFileSync(
+    hooks,
+    [
+      'export async function load(url, context, nextLoad) {',
+      "  if (url.endsWith('/clients/cli/commands/blog.mjs')) {",
+      "    throw new Error('simulated load failure');",
+      '  }',
+      '  return nextLoad(url, context);',
+      '}',
+      '',
+    ].join('\n'),
+  );
+  register = path.join(dir, 'register.mjs');
+  fs.writeFileSync(
+    register,
+    `import {register} from 'node:module';\nregister(${JSON.stringify(pathToFileURL(hooks).href)});\n`,
+  );
+});
+
+afterAll(() => {
+  fs.rmSync(dir, {recursive: true, force: true});
+});
+
+/** @param {string[]} args */
+function run(args) {
+  const res = spawnSync(
+    process.execPath,
+    ['--import', pathToFileURL(register).href, BIN, ...args],
+    {cwd: dir, encoding: 'utf-8', timeout: 20_000},
+  );
+  return {status: res.status, stdout: res.stdout, stderr: res.stderr};
+}
+
+describe('a command that fails to load', () => {
+  it('answers --json with one error envelope, exit 1', () => {
+    const {status, stdout, stderr} = run(['blog', '--json']);
+    expect(status).toBe(1);
+    expect(stderr).toBe('');
+    const envelope = JSON.parse(stdout);
+    expect(envelope).toMatchObject({apiVersion: 1, code: 'ERR_UNKNOWN'});
+    expect(envelope.error).toMatch(/blog.*simulated load failure/);
+  });
+
+  it('reports the failure on stderr without --json, exit 1', () => {
+    const {status, stdout, stderr} = run(['blog']);
+    expect(status).toBe(1);
+    expect(stdout).toBe('');
+    expect(stderr).toMatch(/blog.*failed to load.*simulated load failure/s);
+  });
+
+  it('leaves the other commands working', () => {
+    const {status, stdout} = run(['docs', '--json']);
+    expect(status).toBe(0);
+    expect(JSON.parse(stdout).type).toMatch(/^docs\./);
+  });
+});

package/clients/cli/commands/blog.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'blog',
   displayName: 'astryx blog',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Read the Astryx blog from the published feed',
   description:
     'Reads the design-system blog over its published RSS feed (never the source ' +

package/clients/cli/commands/blog.mjs

@@ -24,6 +24,18 @@ import {resultSet} from '../../../foundation/debug/index.mjs';
 import {doc as blogCommand} from './blog.doc.mjs';
 import {doc as blogFn} from '../../../api/blog/blog.doc.mjs';
 
+/** Every field of a post in the JSON, in order; record() skips empty ones. */
+const POST_FIELDS = [
+  'slug',
+  'title',
+  'description',
+  'date',
+  'type',
+  'authors',
+  'link',
+  'textUrl',
+];
+
 /**
  * @param {import('commander').Command} program
  */
@@ -62,22 +74,25 @@ export function registerBlog(program) {
         const {feedUrl, posts} = result.data;
         if (posts.length === 0) {
           emit(
-            section('Astryx blog', `feed: ${feedUrl}`),
+            section('Astryx blog'),
+            record({feedUrl}),
             text('No posts found in the feed.'),
           );
           return answered;
         }
-        // One record per post — fields mirror the JSON post shape; empty
-        // fields (type/textUrl) are skipped by record().
         emit(
-          section('Astryx blog', `feed: ${feedUrl}`),
-          records(posts, {fields: ['slug', 'title', 'type', 'textUrl']}),
+          section('Astryx blog'),
+          record({feedUrl}),
+          records(posts, {fields: POST_FIELDS}),
           text(`Read one: ${run} astryx blog <slug>`),
         );
       } else {
-        // blog.detail — the feed URL, then the post body emitted verbatim
-        // (code() so article typography/spacing isn't ASCII-normalized).
-        emit(record({feed: result.data.feedUrl}), code(result.data.text));
+        // blog.detail — the post's fields and the feed URL, then the body
+        // verbatim (code() so article typography/spacing isn't ASCII-normalized).
+        emit(
+          record(result.data, {fields: [...POST_FIELDS, 'feedUrl']}),
+          code(result.data.text),
+        );
       }
       return answered;
     },

package/clients/cli/commands/blog.test.mjs

@@ -19,7 +19,10 @@ const FEED = `<?xml version="1.0" encoding="UTF-8"?>
     <item>
       <title>How Astryx works</title>
       <link>${SITE_URL}/blog/how-astryx-works</link>
+      <description>Under the hood &amp; more</description>
       <category>engineering</category>
+      <author>Ada</author>
+      <author>Grace</author>
       <pubDate>Mon, 29 Jun 2026 00:00:00 GMT</pubDate>
       <atom:link rel="alternate" type="text/plain" href="${SITE_URL}/blog/how-astryx-works.txt" />
     </item>
@@ -39,6 +42,23 @@ function stubFetch(routes) {
   });
 }
 
+/**
+ * Every non-empty field prints as a `key: value` line under its JSON key.
+ * @param {string} stdout
+ * @param {Record<string, unknown>} fields
+ */
+function expectFields(stdout, fields) {
+  const lines = stdout.split('\n');
+  for (const [key, value] of Object.entries(fields)) {
+    if (value == null || value === '' || (Array.isArray(value) && !value.length)) continue;
+    const shown = Array.isArray(value) ? value.join(', ') : String(value);
+    expect(
+      lines.some(line => line.startsWith(`${key}:`) && line.trimEnd().endsWith(shown)),
+      `${key}: ${shown}`,
+    ).toBe(true);
+  }
+}
+
 beforeEach(() => {
   vi.stubGlobal(
     'fetch',
@@ -83,10 +103,31 @@ describe('blog CLI — json-enabled', () => {
     const {status, stdout} = await runCli(['blog']);
     expect(status).toBe(0);
     expect(stdout).toMatch(/Astryx blog/);
-    expect(stdout).toMatch(/feed:/);
+    expect(stdout).toMatch(/^feedUrl:/m);
     expect(stdout).toMatch(/how-astryx-works/);
   });
 
+  it('the text list projects every JSON field under its JSON key', async () => {
+    const env = JSON.parse((await runCli(['blog', '--json'])).stdout);
+    const {status, stdout} = await runCli(['blog']);
+    expect(status).toBe(0);
+    expectFields(stdout, {feedUrl: env.data.feedUrl});
+    for (const post of env.data.posts) expectFields(stdout, post);
+    expect(stdout).not.toMatch(/^feed:/m);
+  });
+
+  it('the text detail projects every JSON field, then the post body', async () => {
+    const env = JSON.parse(
+      (await runCli(['blog', 'how-astryx-works', '--json'])).stdout,
+    );
+    const {status, stdout} = await runCli(['blog', 'how-astryx-works']);
+    expect(status).toBe(0);
+    const {text, ...fields} = env.data;
+    expectFields(stdout, fields);
+    expect(stdout).toContain(text);
+    expect(stdout).not.toMatch(/^feed:/m);
+  });
+
   it('surfaces the API error code and exits non-zero for an unknown slug (--json)', async () => {
     const {status, stdout} = await runCli(['blog', 'no-such-post', '--json']);
     expect(status).not.toBe(0);