@astryxdesign/cli 0.1.8-canary.4cc4d7a → 0.1.8-canary.68afe69

package/{src/api → api/blog}/blog.mjs

@@ -10,9 +10,9 @@
  * blog's structure can change freely without touching the CLI.
  */
 
-import {AstryxError} from './error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
-import {SITE_URL, SITE_ORIGIN} from '../lib/site.mjs';
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
+import {SITE_URL, SITE_ORIGIN} from '../../lib/site.mjs';
 
 /** Abort a feed/post fetch that hangs, and cap how much we'll read. */
 const FETCH_TIMEOUT_MS = 15000;

package/{src/api → api/blog}/blog.test.mjs

@@ -9,8 +9,8 @@
 
 import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
 import {blog} from './blog.mjs';
-import {AstryxError} from './error.mjs';
-import {SITE_URL} from '../lib/site.mjs';
+import {AstryxError} from '../error.mjs';
+import {SITE_URL} from '../../lib/site.mjs';
 
 const FEED = `<?xml version="1.0" encoding="UTF-8"?>
 <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">

package/api/build/build.mjs

@@ -0,0 +1,92 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file build API — the "assemble a page" assistant, as data.
+ *
+ * `build()` with no query signals the workflow playbook (`build.help`). With a
+ * query it runs the unified search and groups the results into a composition
+ * KIT (`build.kit`): the closest page templates, the blocks that cover parts,
+ * and the domain components to fill gaps, plus the always-on frame + foundation.
+ *
+ * The kit carries RAW `SearchResultEntry` objects and static name arrays only —
+ * never pre-formatted command strings. All CLI prefixing (formatCliCommand /
+ * getCliInvocation) and the section prose live in the command renderer, so the
+ * JSON shape stays package-manager-agnostic and stable across environments.
+ */
+
+import {search} from '../search/search.mjs';
+
+/** A page at/above this score is a confident direct match. */
+const PAGE_DIRECT = 95;
+/** Below this a page is too weak to offer even as a layout reference. */
+const PAGE_FLOOR = 50;
+/** Below this a block/domain-component match is incidental noise. */
+const DOMAIN_FLOOR = 55;
+
+/**
+ * Always-surfaced primitives. Every page needs a shell + layout/typography/
+ * action atoms, but these never keyword-match an idea ("dashboard" != "Stack"),
+ * so search alone never returns them. Kept here (not the renderer) because they
+ * are ALSO used to exclude these names from the idea-specific `domain` group.
+ */
+const FRAME = ['AppShell', 'TopNav', 'SideNav', 'Layout'];
+const FOUNDATION = [
+  'VStack', 'HStack', 'Grid', 'StackItem', 'Card', 'Section',
+  'Text', 'Heading', 'Button', 'Icon', 'Badge', 'Divider',
+];
+const ALWAYS = new Set([...FRAME, ...FOUNDATION]);
+
+/**
+ * The page-building assistant. No query → the playbook signal; a query → the
+ * grouped composition kit.
+ *
+ * @param {string} [query] what you're building (e.g. "analytics dashboard")
+ * @param {{cwd?: string, type?: import('../../types/search').SearchDomain, limit?: number}} [options]
+ * @returns {Promise<import('../../types/build').BuildHelpResponse | import('../../types/build').BuildKitResponse>}
+ */
+export async function build(query, options = {}) {
+  if (!query || !String(query).trim()) {
+    return {type: 'build.help', data: {playbook: true}};
+  }
+
+  const {cwd = process.cwd(), type, limit = 60} = options;
+  // search()'s JSDoc @returns widens results to object[]; the SearchResponse
+  // shape is the contract (api.d.ts). Cast locally rather than tightening the
+  // search @returns (a separate follow-up).
+  const result = /** @type {import('../../types/search').SearchResponse} */ (
+    await search(query, {cwd, type, limit})
+  );
+  const results = result.data.results;
+
+  const pages = results
+    .filter(r => r.domain === 'template' && r.kind !== 'block' && r.score >= PAGE_FLOOR)
+    .slice(0, 3);
+  const blocks = results
+    .filter(r => r.domain === 'template' && r.kind === 'block' && r.score >= DOMAIN_FLOOR)
+    .slice(0, 5);
+  const domain = results
+    .filter(
+      r =>
+        (r.domain === 'component' || r.domain === 'hook') &&
+        r.score >= DOMAIN_FLOOR &&
+        !ALWAYS.has(r.name),
+    )
+    .slice(0, 6);
+  const directMatch = pages.length > 0 && pages[0].score >= PAGE_DIRECT;
+
+  return {
+    type: 'build.kit',
+    data: {
+      query: result.data.query,
+      // Distinguishes "search found nothing" (renderer shows "No matches")
+      // from a weak-but-non-empty result set (renderer still shows the kit).
+      hasResults: results.length > 0,
+      directMatch,
+      pages,
+      blocks,
+      domain,
+      frame: FRAME,
+      foundation: FOUNDATION,
+    },
+  };
+}

package/api/build/build.test.mjs

@@ -0,0 +1,92 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Tests for the build API (playbook signal + composition kit).
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {build} from './build.mjs';
+
+// api/build/ -> up 3 = packages/cli, up 4 = repo root (has packages/core).
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+
+// build() delegates to search(), whose first (cold) call is slow under vitest.
+vi.setConfig({testTimeout: 30000});
+
+describe('build API', () => {
+  it('no query → build.help playbook signal', async () => {
+    const r = await build();
+    expect(r.type).toBe('build.help');
+    expect(r.data).toEqual({playbook: true});
+  });
+
+  it('query → build.kit with raw entries + static frame/foundation', async () => {
+    const r = await build('dashboard', {cwd: REPO});
+    expect(r.type).toBe('build.kit');
+    if (r.type !== 'build.kit') return;
+    expect(r.data.query).toBe('dashboard');
+    expect(r.data.hasResults).toBe(true);
+    expect(r.data.frame).toContain('AppShell');
+    expect(r.data.foundation).toContain('Button');
+    expect(Array.isArray(r.data.pages)).toBe(true);
+
+    // Entries are RAW SearchResultEntry objects — never package-manager-prefixed
+    // command strings (that formatting is the CLI renderer's job).
+    for (const e of [...r.data.pages, ...r.data.blocks, ...r.data.domain]) {
+      expect(typeof e.name).toBe('string');
+      expect(typeof e.score).toBe('number');
+      expect(e.command).not.toMatch(/^(pnpm|npm|yarn|bun|npx)\b/);
+    }
+  });
+
+  it('excludes always-on frame/foundation names from the domain group', async () => {
+    const r = await build('dashboard', {cwd: REPO});
+    if (r.type !== 'build.kit') throw new Error('expected build.kit');
+    const names = r.data.domain.map(d => d.name);
+    expect(names).not.toContain('Button');
+    expect(names).not.toContain('AppShell');
+  });
+
+  it('applies grouping caps, score floors, and directMatch threshold', async () => {
+    const r = await build('dashboard', {cwd: REPO});
+    if (r.type !== 'build.kit') throw new Error('expected build.kit');
+    const {pages, blocks, domain, directMatch} = r.data;
+
+    // Caps: pages ≤ 3, blocks ≤ 5, domain ≤ 6.
+    expect(pages.length).toBeLessThanOrEqual(3);
+    expect(blocks.length).toBeLessThanOrEqual(5);
+    expect(domain.length).toBeLessThanOrEqual(6);
+
+    // Score floors: pages ≥ PAGE_FLOOR(50); blocks/domain ≥ DOMAIN_FLOOR(55).
+    for (const p of pages) expect(p.score).toBeGreaterThanOrEqual(50);
+    for (const b of blocks) expect(b.score).toBeGreaterThanOrEqual(55);
+    for (const d of domain) expect(d.score).toBeGreaterThanOrEqual(55);
+
+    // directMatch iff the top page is a confident match (PAGE_DIRECT = 95).
+    expect(directMatch).toBe(pages.length > 0 && pages[0].score >= 95);
+
+    // Domain partitioning: pages = non-block templates, blocks = block templates,
+    // domain = components/hooks.
+    for (const p of pages) {
+      expect(p.domain).toBe('template');
+      expect(p.kind).not.toBe('block');
+    }
+    for (const b of blocks) {
+      expect(b.domain).toBe('template');
+      expect(b.kind).toBe('block');
+    }
+    for (const d of domain) expect(['component', 'hook']).toContain(d.domain);
+  });
+
+  it('no matches → build.kit with hasResults=false and empty groups', async () => {
+    const r = await build('zzznomatch99', {cwd: REPO});
+    expect(r.type).toBe('build.kit');
+    if (r.type !== 'build.kit') return;
+    expect(r.data.hasResults).toBe(false);
+    expect(r.data.pages).toHaveLength(0);
+    expect(r.data.blocks).toHaveLength(0);
+    expect(r.data.domain).toHaveLength(0);
+  });
+});

package/{src/api → api/component}/component.mjs

@@ -9,8 +9,8 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
-import {findCoreDir, discoverExternalPackages} from '../utils/paths.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
+import {findCoreDir, discoverExternalPackages} from '../../utils/paths.mjs';
 import {
   CORE_PACKAGE,
   discoverComponents,
@@ -22,12 +22,12 @@ import {
   findIntegrationComponentDoc,
   findIntegrationComponentSource,
   resolveImportPath,
-} from '../lib/component-discovery.mjs';
-import {Project} from '../lib/project.mjs';
-import {loadDocs} from '../lib/component-loader.mjs';
-import {searchComponents} from '../lib/string-utils.mjs';
-import {AstryxError} from './error.mjs';
-import {findShowcase, findRelatedBlocks} from './template.mjs';
+} from '../../lib/component-discovery.mjs';
+import {Project} from '../../lib/project.mjs';
+import {loadDocs} from '../../lib/component-loader.mjs';
+import {searchComponents} from '../../lib/string-utils.mjs';
+import {AstryxError} from '../error.mjs';
+import {findShowcase, findRelatedBlocks} from '../template/template.mjs';
 
 /**
  * A loaded component doc. `loadDocs` returns the authored `.doc.mjs` shape,
@@ -54,12 +54,12 @@ import {findShowcase, findRelatedBlocks} from './template.mjs';
  * component discovery never hard-fails on a malformed/absent integration. An
  * empty list means "core only".
  * @param {string} cwd
- * @returns {Promise<import('../lib/integrations.mjs').LoadedIntegration[]>}
+ * @returns {Promise<import('../../lib/integrations.mjs').LoadedIntegration[]>}
  */
 async function loadIntegrationsSafely(cwd) {
   try {
     const project = await Project.load(cwd);
-    return /** @type {import('../lib/integrations.mjs').LoadedIntegration[]} */ (
+    return /** @type {import('../../lib/integrations.mjs').LoadedIntegration[]} */ (
       project.loadedIntegrations
     );
   } catch {
@@ -69,7 +69,7 @@ async function loadIntegrationsSafely(cwd) {
 
 /**
  * Resolve a loaded integration by package name.
- * @param {import('../lib/integrations.mjs').LoadedIntegration[]} loadedIntegrations
+ * @param {import('../../lib/integrations.mjs').LoadedIntegration[]} loadedIntegrations
  * @param {string} packageName
  */
 function findLoadedIntegration(loadedIntegrations, packageName) {
@@ -195,7 +195,7 @@ export async function component(name, options = {}) {
 
     // All components — merge core + external packages with grouped subcategories
     if (detail === 'compact') {
-      /** @type {Record<string, Array<import('../types/component').ComponentBriefEntry>>} */
+      /** @type {Record<string, Array<import('../../types/component').ComponentBriefEntry>>} */
       const result = {};
       for (const [cat, comps] of Object.entries(components)) {
         result[cat] = [];

package/{src/api → api/discover}/discover.mjs

@@ -4,18 +4,18 @@
  * @file Programmatic API for the discover command.
  */
 
-import {Project} from '../lib/project.mjs';
+import {Project} from '../../lib/project.mjs';
 import {
   scanAllPackages,
   findComponentInPackages,
-} from '../lib/package-scanner.mjs';
-import {loadDocs} from '../lib/component-loader.mjs';
-import {levenshteinDistance} from '../lib/string-utils.mjs';
-import {AstryxError} from './error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
+} from '../../lib/package-scanner.mjs';
+import {loadDocs} from '../../lib/component-loader.mjs';
+import {levenshteinDistance} from '../../lib/string-utils.mjs';
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
 
 /**
- * @typedef {import('../lib/package-scanner.mjs').ScannedPackage} ScannedPackage
+ * @typedef {import('../../lib/package-scanner.mjs').ScannedPackage} ScannedPackage
  */
 
 /**
@@ -46,17 +46,17 @@ function validateDocs(docs) {
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
  * @returns {Promise<
- *   import('../types/discover').DiscoverListResponse |
- *   import('../types/discover').DiscoverDetailResponse |
- *   import('../types/discover').DiscoverDetailDocResponse |
- *   import('../types/discover').DiscoverSearchResponse
+ *   import('../../types/discover').DiscoverListResponse |
+ *   import('../../types/discover').DiscoverDetailResponse |
+ *   import('../../types/discover').DiscoverDetailDocResponse |
+ *   import('../../types/discover').DiscoverSearchResponse
  * >}
  */
 export async function discover(query, options = {}) {
   const {lang = null, zh = false} = options;
   const project = await Project.load();
   const loadedIntegrations =
-    /** @type {import('../lib/integrations.mjs').LoadedIntegration[]} */ (
+    /** @type {import('../../lib/integrations.mjs').LoadedIntegration[]} */ (
       project.loadedIntegrations
     );
   /** @param {ScannedPackage} pkg */
@@ -194,7 +194,7 @@ export async function discover(query, options = {}) {
  * @param {string} compName
  * @param {string} pkgName
  * @param {{lang?: string|null, zh?: boolean}} opts
- * @returns {Promise<import('../types/discover').DiscoverDetailDocResponse>}
+ * @returns {Promise<import('../../types/discover').DiscoverDetailDocResponse>}
  */
 async function resolveComponentDocs(packages, compName, pkgName, {lang, zh}) {
   const pkg = packages.find(p => p.name === pkgName);
@@ -234,7 +234,7 @@ async function resolveComponentDocs(packages, compName, pkgName, {lang, zh}) {
 /**
  * @param {{docPath: string, componentName: string, pkg: ScannedPackage}} result
  * @param {{lang?: string|null, zh?: boolean}} opts
- * @returns {Promise<import('../types/discover').DiscoverDetailDocResponse>}
+ * @returns {Promise<import('../../types/discover').DiscoverDetailDocResponse>}
  */
 async function loadAndValidate(result, {lang, zh}) {
   let docs;

package/{src/api → api/docs}/docs.mjs

@@ -7,9 +7,9 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {pathToFileURL} from 'node:url';
-import {CLI_ROOT} from '../utils/paths.mjs';
-import {AstryxError} from './error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
+import {CLI_ROOT} from '../../utils/paths.mjs';
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
 
 const DOCS_DIR = path.join(CLI_ROOT, 'docs');
 
@@ -30,7 +30,7 @@ function discoverTopics() {
 /**
  * @param {string} docPath
  * @param {{lang?: string|null}} [opts]
- * @returns {Promise<import('../types/docs').DocsDetailResponse['data']>}
+ * @returns {Promise<import('../../types/docs').DocsDetailResponse['data']>}
  */
 async function loadReferenceDocs(docPath, {lang} = {}) {
   const mod = await import(pathToFileURL(docPath).href);
@@ -91,9 +91,9 @@ async function loadReferenceDocs(docPath, {lang} = {}) {
 /**
  * Resolve token-ref blocks by inlining the referenced section's table.
  * This allows section docs to reference token tables without duplicating data.
- * @param {import('../types/docs').DocsDetailResponse['data']} docsData
+ * @param {import('../../types/docs').DocsDetailResponse['data']} docsData
  * @param {Record<string, string>} topics
- * @returns {Promise<import('../types/docs').DocsDetailResponse['data']>}
+ * @returns {Promise<import('../../types/docs').DocsDetailResponse['data']>}
  */
 async function resolveTokenRefs(docsData, topics) {
   const resolved = {...docsData, sections: [...docsData.sections]};
@@ -148,9 +148,9 @@ async function resolveTokenRefs(docsData, topics) {
  * @param {boolean} [options.zh]
  * @param {boolean} [options.dense]
  * @returns {Promise<
- *   import('../types/docs').DocsListResponse |
- *   import('../types/docs').DocsDetailResponse |
- *   import('../types/docs').DocsDetailSectionResponse
+ *   import('../../types/docs').DocsListResponse |
+ *   import('../../types/docs').DocsDetailResponse |
+ *   import('../../types/docs').DocsDetailSectionResponse
  * >}
  */
 export async function docs(topic, section, options = {}) {
@@ -159,7 +159,7 @@ export async function docs(topic, section, options = {}) {
   const topics = discoverTopics();
 
   if (!topic) {
-    /** @type {Array<import('../types/docs').DocsListEntry>} */
+    /** @type {Array<import('../../types/docs').DocsListEntry>} */
     const entries = [];
     for (const [name, docPath] of Object.entries(topics)) {
       try {

package/{src/api → api/doctor}/doctor.mjs

@@ -24,11 +24,11 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {createRequire} from 'node:module';
 
-import {MIN_NODE_VERSION, isNodeVersionSupported} from '../lib/node-version.mjs';
-import {CLI_ROOT, findCoreDir} from '../utils/paths.mjs';
-import {detectPackageManager, getCliInvocation} from '../utils/package-manager.mjs';
-import {findConfigPath, Project} from '../lib/project.mjs';
-import {semverCompare} from '../utils/semver.mjs';
+import {MIN_NODE_VERSION, isNodeVersionSupported} from '../../lib/node-version.mjs';
+import {CLI_ROOT, findCoreDir} from '../../utils/paths.mjs';
+import {detectPackageManager, getCliInvocation} from '../../utils/package-manager.mjs';
+import {findConfigPath, Project} from '../../lib/project.mjs';
+import {semverCompare} from '../../utils/semver.mjs';
 
 const _require = createRequire(import.meta.url);
 

package/{src/api → api/hook}/hook.mjs

@@ -7,12 +7,12 @@
  * The CLI command handler is a thin wrapper around this function.
  */
 
-import {findCoreDir} from '../utils/paths.mjs';
-import {discoverHooks, findHookDoc, getAllHookNames} from '../lib/hook-discovery.mjs';
-import {loadDocs} from '../lib/component-loader.mjs';
-import {levenshteinDistance} from '../lib/string-utils.mjs';
-import {AstryxError} from './error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
+import {findCoreDir} from '../../utils/paths.mjs';
+import {discoverHooks, findHookDoc, getAllHookNames} from '../../lib/hook-discovery.mjs';
+import {loadDocs} from '../../lib/component-loader.mjs';
+import {levenshteinDistance} from '../../lib/string-utils.mjs';
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
 
 /**
  * @param {string} [name]

package/{src/api → api}/index.mjs

@@ -19,13 +19,20 @@
  * // { type: 'hook.detail', data: { name: 'useMediaQuery', ... } }
  */
 
-export {component} from './component.mjs';
-export {docs} from './docs.mjs';
-export {blog} from './blog.mjs';
-export {discover} from './discover.mjs';
-export {template} from './template.mjs';
-export {themeAdd, listThemes} from './theme-add.mjs';
-export {hook} from './hook.mjs';
-export {search} from './search.mjs';
-export {doctor} from './doctor.mjs';
+export {component} from './component/component.mjs';
+export {docs} from './docs/docs.mjs';
+export {blog} from './blog/blog.mjs';
+export {discover} from './discover/discover.mjs';
+export {template} from './template/template.mjs';
+export {themeAdd, listThemes} from './theme/theme-add.mjs';
+export {hook} from './hook/hook.mjs';
+export {search} from './search/search.mjs';
+export {build} from './build/build.mjs';
+export {swizzle} from './swizzle/swizzle.mjs';
+export {doctor} from './doctor/doctor.mjs';
+export {layoutExpand, layoutCheck, layoutGrammar} from './layout/layout.mjs';
+export {
+  validateIntegration,
+  summarizeIssues,
+} from './integration/validate-integration.mjs';
 export {AstryxError} from './error.mjs';

package/{src/api → api/integration}/validate-integration.mjs

@@ -28,13 +28,13 @@ import {
   findManifestPaths,
   loadManifestObject,
   resolvePackageDir,
-} from '../lib/integrations.mjs';
-import {discoverIntegrationCodemods} from '../codemods/integration-discovery.mjs';
-import {discoverIntegrationTemplatesForOne} from './template.mjs';
-import * as componentDiscovery from '../lib/component-discovery.mjs';
+} from '../../lib/integrations.mjs';
+import {discoverIntegrationCodemods} from '../../codemods/integration-discovery.mjs';
+import {discoverIntegrationTemplatesForOne} from '../template/template.mjs';
+import * as componentDiscovery from '../../lib/component-discovery.mjs';
 
 /**
- * @typedef {import('../types/integration').AstryxIntegrationIssue} Issue
+ * @typedef {import('../../types/integration').AstryxIntegrationIssue} Issue
  */
 
 /**
@@ -94,7 +94,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('../../lib/integrations.mjs').LoadedIntegration} integration loaded-integration-shaped object
  * @param {Issue[]} issues
  */
 async function checkCodemods(integration, issues) {
@@ -109,7 +109,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('../../lib/integrations.mjs').LoadedIntegration} integration loaded-integration-shaped object
  * @param {Issue[]} issues
  */
 async function checkTemplates(integration, issues) {
@@ -133,7 +133,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('../../lib/integrations.mjs').LoadedIntegration} integration loaded-integration-shaped object
  * @param {Issue[]} issues
  */
 async function checkComponents(integration, issues) {
@@ -159,7 +159,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('../../lib/integrations.mjs').LoadedIntegration} integration
  * @param {Issue[]} issues
  */
 async function runContributionChecks(integration, issues) {
@@ -182,7 +182,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('../../lib/integrations.mjs').LoadedIntegration} loaded loaded-integration-shaped object
  * @returns {Promise<Issue[]>}
  */
 export async function validateLoadedIntegration(loaded) {
@@ -351,6 +351,34 @@ export async function validateInstalledIntegration(spec, cwd = process.cwd()) {
   });
 }
 
+/**
+ * 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('../../types/validate-integration').ValidateIntegrationResponse>}
+ */
+export async function validateIntegration(pkg, options = {}) {
+  const {cwd = process.cwd()} = options;
+  const result = pkg
+    ? await validateInstalledIntegration(pkg, cwd)
+    : await validateLocalIntegration(cwd);
+  return {
+    type: 'integration.validate',
+    data: {
+      name: result.found ? result.name ?? null : null,
+      version: result.found ? result.version ?? null : null,
+      issues: result.issues,
+    },
+  };
+}
+
 /**
  * Summarize issues by severity.
  * @param {Issue[]} issues

package/{src/api → api/integration}/validate-integration.test.mjs

@@ -24,7 +24,7 @@ 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/src/codemod.mjs'),
+  path.resolve(process.cwd(), 'packages/cli/authoring/codemod.mjs'),
 ).href;
 
 beforeEach(() => {