@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/authoring/integration/integration.doc.mjs

@@ -11,14 +11,21 @@ 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:
+        'Stable logical provider ID. Omit to use package.json#name; set it to the prior package name only when an explicit rename must preserve artifact IDs. If two packages claim the same ID, the package being authored is used, otherwise the first-loaded one, and the CLI warns about the other.',
+      example: "'@acme/widgets'",
+    },
     {
       name: 'components',
       type: 'string',
@@ -50,7 +57,7 @@ export const doc = {
       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`.',
+        'Relative path to a source-theme root with one directory per theme slug. Each directory contains a source module and mandatory same-stem, strongly typed .doc.mjs descriptor. Installed themes appear in `astryx theme list` and can be copied with `astryx theme add`.',
       example: "'./themes'",
     },
     {
@@ -87,9 +94,9 @@ 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.',
+        'Provider identity defaults to package.json#name. During an explicit ' +
+        'package rename, set `providerId` to the prior canonical package name so ' +
+        'existing artifact IDs remain stable. 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/command-result-coverage.test.mjs

@@ -29,17 +29,17 @@ import {program} from './index.mjs';
 import {reportsResult, reportsResultVia} from './lib/define-command.mjs';
 
 /**
- * Commands with no action of their own: bare `astryx layout` prints its
- * subcommand list and does nothing else, so there is no run to report on.
+ * Commands with no action of their own: a group that prints its subcommand
+ * list and does nothing else has no run to report on.
  *
  * Pinned as a SET rather than skipped silently — if a command joins this list,
  * that is a real change to what the CLI does and it should be read, not
- * absorbed. (`theme` is deliberately NOT here: it HAS an action — the one that
- * rejects an unknown subcommand — so it goes through the converter like any
- * other. Its bare form prints help and never returns from that action, which
- * the recorder covers where help is recorded, not here.)
+ * absorbed. Every group ships an action today: `theme`, for instance, HAS one
+ * — the one that rejects an unknown subcommand — so it goes through the
+ * converter like any other. Its bare form prints help and never returns from
+ * that action, which the recorder covers where help is recorded, not here.
  */
-const NO_ACTION_OF_THEIR_OWN = ['layout'];
+const NO_ACTION_OF_THEIR_OWN = [];
 
 /**
  * Commands that record for themselves instead of returning a descriptor.

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);