@astryxdesign/cli 0.2.0 → 0.3.0

package/api/init/run/run.mjs

@@ -9,23 +9,24 @@
  * starter template — with NO prompts, so it behaves identically for humans,
  * agents, CI, and piped I/O. It performs the side effects and returns an
  * `init.run` receipt. Hard errors (unknown feature/template) throw AstryxError
- * with a stable code. Human output is emitted through the injected `logger`
+ * with a stable code. Human output is emitted through the shared `logger`
  * (silent by default) so the CLI keeps its exact plain output and a
  * programmatic caller stays quiet.
  */
 
 import * as path from 'node:path';
 import * as fs from 'node:fs';
-import {CLI_ROOT} from '../../../utils/paths.mjs';
-import {PathSafetyError} from '../../../utils/path-safety.mjs';
-import {getCliInvocation} from '../../../utils/package-manager.mjs';
-import {installAgentDocs} from '../../../lib/agent-docs/agent-docs.mjs';
+import {CLI_ROOT} from '../../../foundation/fs/paths.mjs';
+import {PathSafetyError} from '../../../foundation/fs/path-safety.mjs';
+import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+import {installAgentDocs} from '../../../foundation/agent-docs/agent-docs.mjs';
 import {listTemplates} from '../../template/template.mjs';
 import {AstryxError} from '../../error.mjs';
-import {ERROR_CODES} from '../../../lib/error-codes.mjs';
-import {noopInitLogger} from '../_adapter.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+import {logger} from '../../logger.mjs';
 
 const VALID_FEATURES = ['agents', 'theme', 'template'];
+const VALID_AGENTS = ['claude', 'cursor', 'codex', 'hermes', 'all'];
 
 /**
  * Build the "Next steps" lines printed at the end of `astryx init`.
@@ -43,15 +44,17 @@ export function getNextSteps(invocation) {
   return [
     '',
     '  Next steps:',
-    "    1. Import base styles: import '@astryxdesign/core/reset.css'",
+    '    1. Ensure the @stylexjs/stylex peer dependency is met',
+    `       (run \`${invocation} doctor\` to verify)`,
+    "    2. Import base styles: import '@astryxdesign/core/reset.css'",
     "       and import '@astryxdesign/core/astryx.css'",
-    "    2. Import components: import { Button } from '@astryxdesign/core'",
-    '    3. Optionally add a theme (use the pre-built path for performance):',
+    "    3. Import components: import { Button } from '@astryxdesign/core'",
+    '    4. Optionally add a theme (use the pre-built path for performance):',
     "       import { neutralTheme } from '@astryxdesign/theme-neutral/built'",
     "       import '@astryxdesign/theme-neutral/theme.css'",
     '       <Theme theme={neutralTheme}>...</Theme>',
     `       For custom themes, run \`${invocation} theme build <file>\` to generate the built artifacts.`,
-    `    4. ${invocation} --help for all commands`,
+    `    5. ${invocation} --help for all commands`,
     '',
   ];
 }
@@ -63,12 +66,21 @@ export function getNextSteps(invocation) {
  * generic retry hint and continues without changing the exit code.
  *
  * @param {string} cwd
- * @param {import('../../../types/api').InitOptions} options
+ * @param {import('../init.type.mjs').InitOptions} options
  * @param {string} invocation
- * @param {import('../_adapter.mjs').InitLogger} logger
- * @param {import('../../../types/init').InitRunData} data
+ * @param {import('../init.type.mjs').InitRunData} data
  */
-function applyAgents(cwd, options, invocation, logger, data) {
+function applyAgents(cwd, options, invocation, data) {
+  // Validate --agent up front (a hard error, not a swallowed install failure).
+  // ERR_UNKNOWN_AGENT was defined but never wired — a typo like `--agent claud`
+  // otherwise silently fell back to writing AGENTS.md. Mirrors --features.
+  if (options.agent && !VALID_AGENTS.includes(options.agent)) {
+    throw new AstryxError(
+      `Unknown agent "${options.agent}". Valid agents: ${VALID_AGENTS.join(', ')}`,
+      undefined,
+      ERROR_CODES.ERR_UNKNOWN_AGENT,
+    );
+  }
   try {
     const paths = options.agentDocsPath
       ? Array.isArray(options.agentDocsPath)
@@ -102,10 +114,9 @@ function applyAgents(cwd, options, invocation, logger, data) {
  * @param {string} cwd
  * @param {{templateName?: string}} opts
  * @param {string} invocation
- * @param {import('../_adapter.mjs').InitLogger} logger
- * @param {import('../../../types/init').InitRunData} data
+ * @param {import('../init.type.mjs').InitRunData} data
  */
-function applyTemplate(cwd, {templateName}, invocation, logger, data) {
+function applyTemplate(cwd, {templateName}, invocation, data) {
   const templates = listTemplates();
   if (templates.length === 0) {
     data.template = 'skipped';
@@ -141,9 +152,20 @@ function applyTemplate(cwd, {templateName}, invocation, logger, data) {
   }
 
   const outputDir = path.resolve(cwd, `./src/pages/${templateName}`);
-  const srcPath = path.join(CLI_ROOT, 'templates', 'pages', templateName, 'page.tsx');
+  const srcPath = path.join(CLI_ROOT, 'assets', 'templates', 'pages', templateName, 'page.tsx');
+  const destFile = path.join(outputDir, 'page.tsx');
+  // Don't clobber a user's existing page — same guard the peer template/copy and
+  // theme/add write-leaves apply (init is a public API surface too).
+  if (fs.existsSync(destFile)) {
+    const relDest = path.relative(cwd, destFile) || destFile;
+    throw new AstryxError(
+      `Refusing to overwrite existing file ${relDest}.`,
+      undefined,
+      ERROR_CODES.ERR_FILE_EXISTS,
+    );
+  }
   fs.mkdirSync(outputDir, {recursive: true});
-  fs.copyFileSync(srcPath, path.join(outputDir, 'page.tsx'));
+  fs.copyFileSync(srcPath, destFile);
   const rel = path.relative(cwd, outputDir);
   logger.log(`✓ Template created at ${rel}/page.tsx`);
   data.template = 'created';
@@ -157,11 +179,11 @@ function applyTemplate(cwd, {templateName}, invocation, logger, data) {
  * emitted through `logger` (silent by default); unknown feature or template
  * names throw AstryxError with a stable code.
  *
- * @param {import('../../../types/api').InitOptions} [options]
- * @param {{cwd?: string, logger?: import('../_adapter.mjs').InitLogger}} [ctx]
- * @returns {Promise<import('../../../types/init').InitRunResponse>}
+ * @param {import('../init.type.mjs').InitOptions} [options]
+ * @param {{cwd?: string}} [ctx]
+ * @returns {Promise<import('../init.type.mjs').InitRunResponse>}
  */
-export async function run(options = {}, {cwd = process.cwd(), logger = noopInitLogger} = {}) {
+export async function run(options = {}, {cwd = process.cwd()} = {}) {
   const invocation = getCliInvocation();
 
   // Non-interactive feature install: --features or --all.
@@ -181,7 +203,7 @@ export async function run(options = {}, {cwd = process.cwd(), logger = noopInitL
       );
     }
 
-    /** @type {import('../../../types/init').InitRunData} */
+    /** @type {import('../init.type.mjs').InitRunData} */
     const data = {
       mode: 'features',
       features,
@@ -193,7 +215,7 @@ export async function run(options = {}, {cwd = process.cwd(), logger = noopInitL
       nextSteps: false,
     };
     for (const feature of features) {
-      if (feature === 'agents') applyAgents(cwd, options, invocation, logger, data);
+      if (feature === 'agents') applyAgents(cwd, options, invocation, data);
       if (feature === 'theme') {
         logger.log(
           `✓ For a custom theme, run \`${invocation} theme\` (browse) or \`${invocation} theme add <slug>\` (scaffold).`,
@@ -201,7 +223,7 @@ export async function run(options = {}, {cwd = process.cwd(), logger = noopInitL
         data.theme = true;
       }
       if (feature === 'template') {
-        applyTemplate(cwd, {templateName: options.templateName}, invocation, logger, data);
+        applyTemplate(cwd, {templateName: options.templateName}, invocation, data);
       }
     }
     return {type: 'init.run', data};
@@ -209,7 +231,7 @@ export async function run(options = {}, {cwd = process.cwd(), logger = noopInitL
 
   // No flags: TTY-free default — install the AI agent cheat sheet with NO
   // prompts, then print the getting-started guidance.
-  /** @type {import('../../../types/init').InitRunData} */
+  /** @type {import('../init.type.mjs').InitRunData} */
   const data = {
     mode: 'default',
     features: ['agents'],
@@ -220,7 +242,7 @@ export async function run(options = {}, {cwd = process.cwd(), logger = noopInitL
     templatePath: null,
     nextSteps: true,
   };
-  applyAgents(cwd, options, invocation, logger, data);
+  applyAgents(cwd, options, invocation, data);
   logger.log('');
   logger.log(
     `  Tip: \`${invocation} init --all\` also points you to the theme and page-building workflows.`,

package/api/integration/validate-integration.d.mts

@@ -0,0 +1,81 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Validate an already-LOADED integration (as produced by
+ * `loadIntegrations` in lib/integrations.mjs — absolute contribution roots
+ * plus identity) and return its issues. This is the reuse seam for everyday
+ * commands that have already loaded the configured integrations and want the
+ * SAME validators that `validate-integration` runs, without re-resolving the
+ * manifest from disk.
+ *
+ * The manifest schema is intentionally NOT re-validated here: `loadIntegrations`
+ * already validated it (and throws otherwise), so by the time a command holds a
+ * loaded integration the manifest is known-good. We re-run the on-disk
+ * contribution checks (roots + codemods/templates/components) because those can
+ * regress independently of the manifest (a deleted directory, a broken template).
+ *
+ * @param {import('./validate-integration.type.mjs').LoadedIntegration} loaded loaded-integration-shaped object
+ * @returns {Promise<Issue[]>}
+ */
+export function validateLoadedIntegration(loaded: import("./validate-integration.type.mjs").LoadedIntegration): Promise<Issue[]>;
+/**
+ * Validate the LOCAL integration package rooted at `cwd`: nearest package.json
+ * + a single sibling astryx.integration.{ts,mjs,js}. A missing manifest yields
+ * `found: false` (guidance, not an error) so callers stay exit-0.
+ * @param {string} [cwd]
+ * @returns {Promise<ValidateResult>}
+ */
+export function validateLocalIntegration(cwd?: string): Promise<ValidateResult>;
+/**
+ * Validate an INSTALLED integration package resolved from `cwd`/node_modules.
+ * @param {string} spec package name
+ * @param {string} [cwd]
+ * @returns {Promise<ValidateResult>}
+ */
+export function validateInstalledIntegration(spec: string, cwd?: string): Promise<ValidateResult>;
+/**
+ * Unified entry: validate the LOCAL integration (no `pkg`) or an INSTALLED one
+ * (`pkg` given) and return the `integration.validate` envelope. The no-manifest
+ * local case is guidance, not an error — it comes back with `name: null` and no
+ * issues so the CLI can print a hint and stay exit-0.
+ *
+ * This is the seam that keeps the CLI a thin wrapper: the command handler calls
+ * this and only chooses how to render (human vs --json) + the exit code.
+ *
+ * @param {string} [pkg] installed package name; omit to validate the cwd package
+ * @param {{cwd?: string}} [options]
+ * @returns {Promise<import('./validate-integration.type.mjs').ValidateIntegrationResponse>}
+ */
+export function validateIntegration(pkg?: string, options?: {
+    cwd?: string;
+}): Promise<import("./validate-integration.type.mjs").ValidateIntegrationResponse>;
+/**
+ * Summarize issues by severity.
+ * @param {Issue[]} issues
+ * @returns {{errors: number, warnings: number}}
+ */
+export function summarizeIssues(issues: Issue[]): {
+    errors: number;
+    warnings: number;
+};
+export type Issue = import("../../foundation/integrations/issue").AstryxIntegrationIssue;
+export type ValidateResult = {
+    /**
+     * Whether an integration manifest was located.
+     */
+    found: boolean;
+    /**
+     * Integration package name (from package.json).
+     */
+    name?: string | undefined;
+    /**
+     * Integration package version.
+     */
+    version?: string | undefined;
+    /**
+     * Absolute path to the loaded manifest.
+     */
+    manifestFile?: string | undefined;
+    issues: Issue[];
+};

package/api/integration/validate-integration.mjs

@@ -24,17 +24,18 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import {assertWithin} from '../../foundation/fs/path-safety.mjs';
 import {
   findManifestPaths,
   loadManifestObject,
   resolvePackageDir,
-} from '../../lib/integrations.mjs';
-import {discoverIntegrationCodemods} from '../../codemods/integration-discovery.mjs';
+} from '../../foundation/integrations/integrations.mjs';
+import {discoverIntegrationCodemods} from '../../assets/codemods/integration-discovery.mjs';
 import {discoverIntegrationTemplatesForOne} from '../template/template.mjs';
-import * as componentDiscovery from '../../lib/component-discovery.mjs';
+import * as componentDiscovery from '../../foundation/discovery/component-discovery.mjs';
 
 /**
- * @typedef {import('../../types/integration').AstryxIntegrationIssue} Issue
+ * @typedef {import('../../foundation/integrations/issue').AstryxIntegrationIssue} Issue
  */
 
 /**
@@ -94,7 +95,7 @@ function checkRoots(resolved, issues) {
  * Validate the integration's codemods via the landed discovery. Discovery is
  * strict (throws on bad export / duplicate id); we convert any throw into an
  * `invalid_codemod` error.
- * @param {import('../../lib/integrations.mjs').LoadedIntegration} integration loaded-integration-shaped object
+ * @param {import('./validate-integration.type.mjs').LoadedIntegration} integration loaded-integration-shaped object
  * @param {Issue[]} issues
  */
 async function checkCodemods(integration, issues) {
@@ -109,7 +110,7 @@ async function checkCodemods(integration, issues) {
 /**
  * Validate the integration's templates via the landed discovery. Per-template
  * problems are reported as `invalid_template` errors.
- * @param {import('../../lib/integrations.mjs').LoadedIntegration} integration loaded-integration-shaped object
+ * @param {import('./validate-integration.type.mjs').LoadedIntegration} integration loaded-integration-shaped object
  * @param {Issue[]} issues
  */
 async function checkTemplates(integration, issues) {
@@ -133,7 +134,7 @@ async function checkTemplates(integration, issues) {
  * `discoverIntegrationComponents` returns ownership records and does not throw
  * on a missing same-stem source — it records `sourcePath: null`. We surface
  * each such record as an `invalid_component` error.
- * @param {import('../../lib/integrations.mjs').LoadedIntegration} integration loaded-integration-shaped object
+ * @param {import('./validate-integration.type.mjs').LoadedIntegration} integration loaded-integration-shaped object
  * @param {Issue[]} issues
  */
 async function checkComponents(integration, issues) {
@@ -159,7 +160,7 @@ async function checkComponents(integration, issues) {
 
 /**
  * Run every contribution validator against a loaded-integration-shaped object.
- * @param {import('../../lib/integrations.mjs').LoadedIntegration} integration
+ * @param {import('./validate-integration.type.mjs').LoadedIntegration} integration
  * @param {Issue[]} issues
  */
 async function runContributionChecks(integration, issues) {
@@ -182,7 +183,7 @@ async function runContributionChecks(integration, issues) {
  * contribution checks (roots + codemods/templates/components) because those can
  * regress independently of the manifest (a deleted directory, a broken template).
  *
- * @param {import('../../lib/integrations.mjs').LoadedIntegration} loaded loaded-integration-shaped object
+ * @param {import('./validate-integration.type.mjs').LoadedIntegration} loaded loaded-integration-shaped object
  * @returns {Promise<Issue[]>}
  */
 export async function validateLoadedIntegration(loaded) {
@@ -261,8 +262,20 @@ async function validateAtPackageDir(packageDir, identity) {
   }
 
   /** @param {string | null | undefined} value */
-  const resolveRoot = value =>
-    value == null ? undefined : path.resolve(packageDir, value);
+  const resolveRoot = (value, kind = 'contribution root') => {
+    if (value == null) return undefined;
+    try {
+      return assertWithin(value, packageDir, {label: kind});
+    } catch {
+      // If the root escapes the package, report an issue instead of crashing.
+      result.issues.push({
+        code: 'root_outside_package',
+        severity: 'error',
+        message: `The ${kind} "${value}" resolves outside the integration package directory. Contribution roots must stay within the package.`,
+      });
+      return undefined;
+    }
+  };
 
   const loaded = {
     name: identity.name,
@@ -324,7 +337,22 @@ export async function validateLocalIntegration(cwd = process.cwd()) {
  * @returns {Promise<ValidateResult>}
  */
 export async function validateInstalledIntegration(spec, cwd = process.cwd()) {
-  const packageDir = resolvePackageDir(spec, cwd);
+  // resolvePackageDir throws (path-safety guard) on a spec with path segments,
+  // `..`, or an absolute path. Every other malformed input to this command
+  // degrades into a diagnostic — so catch it here and return an issue instead
+  // of letting the throw escape to a raw stack (human) / generic ERR_UNKNOWN
+  // (--json).
+  let packageDir;
+  try {
+    packageDir = resolvePackageDir(spec, cwd);
+  } catch (err) {
+    return {
+      found: true,
+      name: spec,
+      version: undefined,
+      issues: [error('invalid_package_spec', /** @type {any} */ (err).message)],
+    };
+  }
   const pkgJsonPath = path.join(packageDir, 'package.json');
 
   /** @type {{name?: string, version?: string}} */
@@ -362,7 +390,7 @@ export async function validateInstalledIntegration(spec, cwd = process.cwd()) {
  *
  * @param {string} [pkg] installed package name; omit to validate the cwd package
  * @param {{cwd?: string}} [options]
- * @returns {Promise<import('../../types/validate-integration').ValidateIntegrationResponse>}
+ * @returns {Promise<import('./validate-integration.type.mjs').ValidateIntegrationResponse>}
  */
 export async function validateIntegration(pkg, options = {}) {
   const {cwd = process.cwd()} = options;

package/api/integration/validate-integration.test.mjs

@@ -12,7 +12,6 @@
 import {afterEach, beforeEach, describe, expect, it} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {pathToFileURL} from 'node:url';
 import {
   validateLocalIntegration,
   validateInstalledIntegration,
@@ -21,12 +20,6 @@ import {
 
 let tmpDir;
 
-// Absolute file:// URL to the codemod helper so codemod modules in the temp
-// package can import createCodemod without node_modules wiring.
-const codemodModuleUrl = pathToFileURL(
-  path.resolve(process.cwd(), 'packages/cli/authoring/codemod.mjs'),
-).href;
-
 beforeEach(() => {
   tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-validate-it-'));
 });
@@ -64,8 +57,7 @@ describe('validate-integration API', () => {
     fs.mkdirSync(cmDir, {recursive: true});
     fs.writeFileSync(
       path.join(cmDir, 'drop-foo.mjs'),
-      `import {createCodemod} from ${JSON.stringify(codemodModuleUrl)};\n` +
-        `export default createCodemod({ title: 'Drop foo', transform: (file) => file.source });\n`,
+      `export default { type: 'code', title: 'Drop foo', transform: (file) => file.source };\n`,
     );
 
     const result = await validateLocalIntegration(pkgDir);
@@ -219,4 +211,30 @@ describe('validate-integration API', () => {
     const result = await validateLocalIntegration(pkgDir);
     expect(byCode(result.issues, 'invalid_component')).toHaveLength(1);
   });
+
+  it('degrades a path-unsafe package spec (..) into a diagnostic instead of crashing', async () => {
+    const consumer = path.join(tmpDir, 'consumer');
+    fs.mkdirSync(consumer, {recursive: true});
+    fs.writeFileSync(
+      path.join(consumer, 'package.json'),
+      JSON.stringify({name: 'consumer'}),
+    );
+    // resolvePackageDir throws on a spec with `..`; it must be caught and
+    // surfaced as an issue, not escape as a raw stack / generic ERR_UNKNOWN.
+    const result = await validateInstalledIntegration('../evil', consumer);
+    expect(result.found).toBe(true);
+    expect(byCode(result.issues, 'invalid_package_spec')).toHaveLength(1);
+    expect(summarizeIssues(result.issues).errors).toBeGreaterThan(0);
+  });
+
+  it('degrades an absolute package spec into a diagnostic', async () => {
+    const consumer = path.join(tmpDir, 'consumer');
+    fs.mkdirSync(consumer, {recursive: true});
+    fs.writeFileSync(
+      path.join(consumer, 'package.json'),
+      JSON.stringify({name: 'consumer'}),
+    );
+    const result = await validateInstalledIntegration('/etc/passwd', consumer);
+    expect(byCode(result.issues, 'invalid_package_spec')).toHaveLength(1);
+  });
 });

package/api/integration/validate-integration.type.d.mts

@@ -0,0 +1,36 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * A loaded integration manifest — the shape `validateLoadedIntegration` accepts.
+ * Colocated here (rather than referencing the internal `lib/integrations`
+ * module) so the generated public `./api` surface stays self-contained.
+ */
+export type LoadedIntegration = {
+    name: string;
+    version?: string | undefined;
+    components?: string | undefined;
+    templates?: string | undefined;
+    codemods?: string | undefined;
+    issuesUrl?: string | undefined;
+    __spec: string;
+    __packageDir: string;
+    __manifestFile: string;
+};
+/**
+ * Options for `validateIntegration()`.
+ */
+export type ValidateIntegrationOptions = {
+    cwd?: string | undefined;
+};
+/**
+ * `astryx --json validate-integration [package]`.
+ */
+export type ValidateIntegrationResponse = {
+    type: "integration.validate";
+    data: {
+        name: string | null;
+        version: string | null;
+        issues: import("../../foundation/integrations/issue").AstryxIntegrationIssue[];
+    };
+};

package/api/integration/validate-integration.type.mjs

@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated types for the `validate-integration` command — source of truth
+ * for its options + response. `AstryxIntegrationIssue` stays shared in
+ * types/integration.d.ts (it's not command-owned). Re-exported by
+ * types/validate-integration.d.ts so the public surface resolves the same names.
+ */
+
+/**
+ * A loaded integration manifest — the shape `validateLoadedIntegration` accepts.
+ * Colocated here (rather than referencing the internal `lib/integrations`
+ * module) so the generated public `./api` surface stays self-contained.
+ * @typedef {object} LoadedIntegration
+ * @property {string} name
+ * @property {string} [version]
+ * @property {string} [components]
+ * @property {string} [templates]
+ * @property {string} [codemods]
+ * @property {string} [issuesUrl]
+ * @property {string} __spec
+ * @property {string} __packageDir
+ * @property {string} __manifestFile
+ */
+
+/**
+ * Options for `validateIntegration()`.
+ * @typedef {object} ValidateIntegrationOptions
+ * @property {string} [cwd]
+ */
+
+/**
+ * `astryx --json validate-integration [package]`.
+ * @typedef {object} ValidateIntegrationResponse
+ * @property {'integration.validate'} type
+ * @property {{name: string | null, version: string | null, issues: import('../../foundation/integrations/issue').AstryxIntegrationIssue[]}} data
+ */
+
+export {};

package/api/json/index.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Type surface for the `@astryxdesign/cli/json` export — the out-of-process
+ * consumer's view of `astryx --json` output.
+ *
+ * It re-exports every command's response types (the same colocated
+ * `api/<cmd>/<cmd>.type.mjs` source of truth the in-process `./api` surface
+ * uses) plus the shared response contract: the envelope/error/suggestion base
+ * (foundation/response/base), the error-code union (foundation/response/error-codes),
+ * and the manifest types (clients/cli/lib/manifest). This keeps `./json` and
+ * `./api` describing the same data from one source, with no drift.
+ */
+
+export type * from '../component/component.type.mjs';
+export type * from '../docs/docs.type.mjs';
+export type * from '../blog/blog.type.mjs';
+export type * from '../discover/discover.type.mjs';
+export type * from '../template/template.type.mjs';
+export type * from '../theme/theme.type.mjs';
+export type * from '../hook/hook.type.mjs';
+export type * from '../search/search.type.mjs';
+export type * from '../build/build.type.mjs';
+export type * from '../swizzle/swizzle.type.mjs';
+export type * from '../upgrade/upgrade.type.mjs';
+export type * from '../init/init.type.mjs';
+export type * from '../doctor/doctor.type.mjs';
+export type * from '../layout/layout.type.mjs';
+export type * from '../integration/validate-integration.type.mjs';
+export type * from '../../foundation/response/base';
+export type * from '../../foundation/response/error-codes';
+export type * from '../../clients/cli/lib/manifest';

package/api/json/parse.d.mts

@@ -0,0 +1,28 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file Consumer utilities for parsing Astryx CLI JSON output.
+ *
+ * Exported via `@astryxdesign/cli/json`:
+ *   import { parseResponse, isError, assertResponse } from '@astryxdesign/cli/json';
+ */
+/**
+ * Parse raw CLI output into a typed result.
+ * Consumer types are declared in types/base.d.ts — this is the runtime implementation.
+ * @param {unknown} raw
+ */
+export function parseResponse(raw: unknown): any;
+/**
+ * Type guard: returns true if result is a CLI error.
+ * @param {unknown} result
+ * @returns {boolean}
+ */
+export function isError(result: unknown): boolean;
+/**
+ * Assert a specific response type. Throws on error or type mismatch.
+ * Consumer types are declared in types/base.d.ts — this is the runtime implementation.
+ * @param {unknown} raw
+ * @param {string} expectedType
+ */
+export function assertResponse(raw: unknown, expectedType: string): any;

package/api/json/parse.test.mjs

@@ -0,0 +1,76 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated tests for parse.mjs — the CONSUMER-FACING JSON helpers
+ * exported as `@astryxdesign/cli/json`. These lock the contract downstream
+ * consumers depend on:
+ *   - parseResponse JSON-parses a string but passes a non-string through
+ *     by reference (idempotent on already-parsed envelopes),
+ *   - parseResponse propagates a SyntaxError on malformed JSON,
+ *   - isError is a safe type-guard that is true only for objects carrying an
+ *     `error` key (never throws on null/undefined/primitives),
+ *   - assertResponse returns the envelope on a type match, throws the CLI's
+ *     error string on an error envelope, and throws a descriptive message on
+ *     a type mismatch.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {parseResponse, isError, assertResponse} from './parse.mjs';
+
+describe('parseResponse', () => {
+  it('parses a JSON string into an object', () => {
+    expect(parseResponse('{"type":"t","data":1}')).toEqual({
+      type: 't',
+      data: 1,
+    });
+  });
+
+  it('passes a non-string value through by reference (idempotent)', () => {
+    const already = {type: 't', data: 1};
+    expect(parseResponse(already)).toBe(already);
+    expect(parseResponse(null)).toBeNull();
+  });
+
+  it('throws a SyntaxError on malformed JSON', () => {
+    expect(() => parseResponse('{not json')).toThrow(SyntaxError);
+  });
+});
+
+describe('isError', () => {
+  it('is true only for an object with an `error` key', () => {
+    expect(isError({error: 'boom'})).toBe(true);
+    expect(isError({type: 'ok'})).toBe(false);
+  });
+
+  it('never throws on null / undefined / primitives', () => {
+    expect(isError(null)).toBe(false);
+    expect(isError(undefined)).toBe(false);
+    expect(isError('error')).toBe(false);
+    expect(isError(5)).toBe(false);
+    expect(isError(true)).toBe(false);
+  });
+});
+
+describe('assertResponse', () => {
+  it('returns the parsed envelope when the type matches', () => {
+    expect(assertResponse('{"type":"foo","data":42}', 'foo')).toEqual({
+      type: 'foo',
+      data: 42,
+    });
+  });
+
+  it('accepts an already-parsed object', () => {
+    const env = {type: 'foo', data: 1};
+    expect(assertResponse(env, 'foo')).toBe(env);
+  });
+
+  it('throws the CLI error string on an error envelope', () => {
+    expect(() => assertResponse('{"error":"boom"}', 'foo')).toThrow('boom');
+  });
+
+  it('throws a descriptive message on a type mismatch', () => {
+    expect(() => assertResponse('{"type":"bar"}', 'foo')).toThrow(
+      'Expected type "foo", got "bar"',
+    );
+  });
+});