@astryxdesign/cli 0.2.0 → 0.3.0

package/api/search/search.d.mts

@@ -0,0 +1,89 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Light stemmer: strips common English suffixes so "charts"/"charting" and
+ * "chart" share a root. Deliberately crude (no Porter) — good enough to bridge
+ * plural/gerund gaps without a dependency.
+ * @param {string} w
+ * @returns {string}
+ */
+export function stem(w: string): string;
+/**
+ * Split a query into meaningful content tokens (lowercased, stopwords + very
+ * short words removed). Empty for single-word queries (callers fall back to
+ * whole-phrase scoring).
+ * @param {string} term - Already-lowercased query.
+ * @returns {string[]}
+ */
+export function tokenizeQuery(term: string): string[];
+/**
+ * @param {string} term - Lowercased full query.
+ * @param {string[]} tokens - Content tokens from tokenizeQuery(term).
+ * @param {Candidate} candidate
+ * @returns {{score: number, reason: string} | null}
+ */
+export function scoreQuery(term: string, tokens: string[], candidate: Candidate): {
+    score: number;
+    reason: string;
+} | null;
+/**
+ * Score a single candidate against the search term across name, keywords,
+ * and prose signals. Returns the best (highest) score plus a human reason,
+ * or null if nothing matched above the floor.
+ *
+ * @param {string} term - Lowercased search term.
+ * @param {object} candidate
+ * @param {string} candidate.name - Primary identifier (component/hook name, topic, template name).
+ * @param {string[]} [candidate.keywords]
+ * @param {string} [candidate.description]
+ * @param {string[]} [candidate.prose] - Extra free-text blobs (doc section text, best practices).
+ * @returns {{score: number, reason: string} | null}
+ */
+export function scoreCandidate(term: string, { name, keywords, description, prose }: {
+    name: string;
+    keywords?: string[] | undefined;
+    description?: string | undefined;
+    prose?: string[] | undefined;
+}): {
+    score: number;
+    reason: string;
+} | null;
+/**
+ * Unified ranked search across components, hooks, docs, and templates.
+ *
+ * @param {string} query - Free-text search term.
+ * @param {object} [options]
+ * @param {string} [options.cwd]
+ * @param {'component'|'hook'|'doc'|'template'} [options.type] - Restrict to one domain.
+ * @param {number} [options.limit] - Max results (default 20).
+ * @returns {Promise<{type: 'search', data: {query: string, results: Array<object>}}>}
+ */
+export function search(query: string, options?: {
+    cwd?: string | undefined;
+    type?: "component" | "template" | "hook" | "doc" | undefined;
+    limit?: number | undefined;
+}): Promise<{
+    type: "search";
+    data: {
+        query: string;
+        results: Array<object>;
+    };
+}>;
+/** Valid domain filters for `--type`. */
+export const SEARCH_DOMAINS: string[];
+/**
+ * A search candidate gathered from one content domain. Extra underscore-
+ * prefixed fields carry domain-specific payload used only by {@link toResult}.
+ */
+export type Candidate = {
+    domain: "component" | "hook" | "doc" | "template";
+    name: string;
+    keywords?: string[] | undefined;
+    description?: string | undefined;
+    prose?: string[] | undefined;
+    _import?: string | undefined;
+    _title?: string | undefined;
+    _displayName?: string | undefined;
+    _kind?: "block" | "page" | undefined;
+};

package/api/search/search.mjs

@@ -33,18 +33,19 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {pathToFileURL} from 'node:url';
-import {findCoreDir, CLI_ROOT} from '../../utils/paths.mjs';
+import {findCoreDir, CLI_ROOT} from '../../foundation/fs/paths.mjs';
 import {
   discoverComponents,
   findComponentReadme,
   resolveImportPath,
-} from '../../lib/component-discovery.mjs';
-import {discoverHooks, findHookDoc} from '../../lib/hook-discovery.mjs';
-import {levenshteinDistance} from '../../lib/string-utils.mjs';
+} from '../../foundation/discovery/component-discovery.mjs';
+import {discoverHooks, findHookDoc} from '../../foundation/discovery/hook-discovery.mjs';
+import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
 import {discoverTemplates, extractComponents} from '../template/template.mjs';
 import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 
-const DOCS_DIR = path.join(CLI_ROOT, 'docs');
+const DOCS_DIR = path.join(CLI_ROOT, 'assets', 'docs');
 
 /**
  * A search candidate gathered from one content domain. Extra underscore-
@@ -558,15 +559,32 @@ export async function search(query, options = {}) {
   const {cwd = process.cwd(), type, limit = 20} = options;
 
   if (!query || !String(query).trim()) {
-    throw new AstryxError('A search query is required', [
-      {name: 'astryx search button', reason: 'example'},
-    ]);
+    throw new AstryxError(
+      'A search query is required',
+      [{name: 'astryx search button', reason: 'example'}],
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
   }
 
   if (type && !SEARCH_DOMAINS.includes(type)) {
     throw new AstryxError(
       `Unknown --type "${type}"`,
       SEARCH_DOMAINS.map(d => ({name: d, reason: 'valid type'})),
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
+
+  // Validate limit here (not just in the CLI) so direct API callers get the same
+  // contract: a non-positive or non-integer limit is an error, never a silent
+  // "return everything". (Previously `limit <= 0` fell through to the full set.)
+  if (
+    limit != null &&
+    (!Number.isInteger(limit) || limit <= 0)
+  ) {
+    throw new AstryxError(
+      `Invalid limit "${limit}". Must be a positive integer.`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
     );
   }
 
@@ -610,7 +628,7 @@ export async function search(query, options = {}) {
       a.name.localeCompare(b.name),
   );
 
-  const limited = limit > 0 ? scored.slice(0, limit) : scored;
+  const limited = scored.slice(0, limit);
 
   return {type: 'search', data: {query: String(query).trim(), results: limited}};
 }

package/api/search/search.test.mjs

@@ -0,0 +1,94 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated tests for the `search` leaf (api/search/search.mjs), run
+ * against the real @astryxdesign/core registry. `search` had no api-level tests;
+ * this locks the envelope, ranking invariants, the `--type`/limit handling, and
+ * the error paths.
+ *
+ * The API validates its own inputs (not just the CLI): a non-positive/non-integer
+ * `limit`, an empty query, and a bad `--type` all throw AstryxError with the
+ * ERR_INVALID_ARGUMENT code, so a direct `@astryxdesign/cli/api` caller gets the
+ * same contract as `astryx search` on the command line.
+ */
+
+import {describe, it, expect} from 'vitest';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {search, SEARCH_DOMAINS} from './search.mjs';
+
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+const cwd = REPO;
+const SLOW = 30_000;
+
+describe('search leaf — envelope + ranking', () => {
+  it('returns a `search` envelope with query + results', async () => {
+    const r = await search('button', {cwd});
+    expect(r.type).toBe('search');
+    expect(r.data.query).toBe('button');
+    expect(Array.isArray(r.data.results)).toBe(true);
+    expect(r.data.results.length).toBeGreaterThan(0);
+  }, SLOW);
+
+  it('returns an empty result set (not an error) for a no-match query', async () => {
+    const r = await search('zzznomatch99', {cwd});
+    expect(r.type).toBe('search');
+    expect(r.data.results).toEqual([]);
+  }, SLOW);
+
+  it('defaults to at most 20 results', async () => {
+    const r = await search('button', {cwd});
+    expect(r.data.results.length).toBeLessThanOrEqual(20);
+  }, SLOW);
+
+  it('caps results to a positive limit', async () => {
+    const r = await search('button', {cwd, limit: 2});
+    expect(r.data.results.length).toBeLessThanOrEqual(2);
+  }, SLOW);
+});
+
+describe('search leaf — --type filter', () => {
+  it('restricts results to the requested domain', async () => {
+    const r = await search('button', {cwd, type: 'component'});
+    expect(r.data.results.every(x => x.domain === 'component')).toBe(true);
+  }, SLOW);
+
+  it('exposes the valid domain list', () => {
+    expect(SEARCH_DOMAINS).toEqual(expect.arrayContaining(['component', 'hook', 'doc', 'template']));
+  });
+});
+
+describe('search leaf — error paths (pinned)', () => {
+  it('throws ERR_INVALID_ARGUMENT when the query is empty/whitespace', async () => {
+    await expect(search('   ', {cwd})).rejects.toMatchObject({
+      code: 'ERR_INVALID_ARGUMENT',
+      message: expect.stringMatching(/query is required/i),
+    });
+  }, SLOW);
+
+  it('throws ERR_INVALID_ARGUMENT for an unknown --type', async () => {
+    await expect(
+      search('button', {cwd, type: /** @type {any} */ ('bogus')}),
+    ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
+  }, SLOW);
+});
+
+describe('search leaf — limit validation (API matches the CLI contract)', () => {
+  it('throws ERR_INVALID_ARGUMENT for a limit of 0 (no longer returns everything)', async () => {
+    await expect(search('button', {cwd, limit: 0})).rejects.toMatchObject({
+      code: 'ERR_INVALID_ARGUMENT',
+    });
+  }, SLOW);
+
+  it('throws ERR_INVALID_ARGUMENT for a negative limit', async () => {
+    await expect(search('button', {cwd, limit: -5})).rejects.toMatchObject({
+      code: 'ERR_INVALID_ARGUMENT',
+    });
+  }, SLOW);
+
+  it('throws ERR_INVALID_ARGUMENT for a non-integer limit', async () => {
+    await expect(search('button', {cwd, limit: 2.5})).rejects.toMatchObject({
+      code: 'ERR_INVALID_ARGUMENT',
+    });
+  }, SLOW);
+});

package/api/search/search.type.d.mts

@@ -0,0 +1,70 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * The domain a search result belongs to.
+ */
+export type SearchDomain = "component" | "hook" | "doc" | "template";
+/**
+ * A single ranked search result, tagged with its domain.
+ */
+export type SearchResultEntry = {
+    /**
+     * - Which content domain this result came from.
+     */
+    domain: SearchDomain;
+    /**
+     * - Primary identifier (component/hook name, doc topic, template dir).
+     */
+    name: string;
+    /**
+     * - Relevance score (higher is better).
+     */
+    score: number;
+    /**
+     * - Human-readable reason the candidate matched (e.g. `keyword "button"`).
+     */
+    reason: string;
+    /**
+     * - One-line description, when available.
+     */
+    description: string;
+    /**
+     * - Follow-up command to act on this result (e.g. `astryx component Button`).
+     */
+    command: string;
+    /**
+     * - Import path — present for component and hook results.
+     */
+    import?: string | undefined;
+    /**
+     * - Doc title — present for doc results.
+     */
+    title?: string | undefined;
+    /**
+     * - Friendly display name — present for template results.
+     */
+    displayName?: string | undefined;
+    /**
+     * - Template kind (`page` | `block`) — present for template results.
+     */
+    kind?: "block" | "page" | undefined;
+};
+/**
+ * xds --json search <query>
+ */
+export type SearchResponse = {
+    type: "search";
+    data: {
+        query: string;
+        results: SearchResultEntry[];
+    };
+};
+/**
+ * Options for `search()`.
+ */
+export type SearchOptions = {
+    cwd?: string | undefined;
+    type?: SearchDomain | undefined;
+    limit?: number | undefined;
+};

package/api/search/search.type.mjs

@@ -0,0 +1,47 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated types for the `search` command — source of truth for the
+ * `astryx search <query>` JSON response shapes. `types/search.d.ts` re-exports
+ * these so the public `./types/search` entrypoint (and the types barrel) keep
+ * working unchanged.
+ */
+
+/**
+ * The domain a search result belongs to.
+ * @typedef {'component' | 'hook' | 'doc' | 'template'} SearchDomain
+ */
+
+/**
+ * A single ranked search result, tagged with its domain.
+ * @typedef {object} SearchResultEntry
+ * @property {SearchDomain} domain - Which content domain this result came from.
+ * @property {string} name - Primary identifier (component/hook name, doc topic, template dir).
+ * @property {number} score - Relevance score (higher is better).
+ * @property {string} reason - Human-readable reason the candidate matched (e.g. `keyword "button"`).
+ * @property {string} description - One-line description, when available.
+ * @property {string} command - Follow-up command to act on this result (e.g. `astryx component Button`).
+ * @property {string} [import] - Import path — present for component and hook results.
+ * @property {string} [title] - Doc title — present for doc results.
+ * @property {string} [displayName] - Friendly display name — present for template results.
+ * @property {'page' | 'block'} [kind] - Template kind (`page` | `block`) — present for template results.
+ */
+
+/**
+ * xds --json search <query>
+ * @typedef {object} SearchResponse
+ * @property {'search'} type
+ * @property {object} data
+ * @property {string} data.query
+ * @property {SearchResultEntry[]} data.results
+ */
+
+/**
+ * Options for `search()`.
+ * @typedef {object} SearchOptions
+ * @property {string} [cwd]
+ * @property {SearchDomain} [type]
+ * @property {number} [limit]
+ */
+
+export {};

package/api/swizzle/_adapter.d.mts

@@ -0,0 +1,12 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Locate @astryxdesign/core for `cwd` and list its swizzlable components.
+ * @param {string} cwd
+ * @returns {{coreDir: string, components: string[]}}
+ */
+export function resolveCore(cwd: string): {
+    coreDir: string;
+    components: string[];
+};

package/api/swizzle/_adapter.mjs

@@ -11,8 +11,8 @@
  * (ERR_CORE_NOT_FOUND) when core can't be located.
  */
 
-import {findCoreDir, listComponents} from '../../utils/paths.mjs';
-import {ERROR_CODES} from '../../lib/error-codes.mjs';
+import {findCoreDir, listComponents} from '../../foundation/fs/paths.mjs';
+import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {AstryxError} from '../error.mjs';
 
 /**

package/api/swizzle/_github.d.mts

@@ -0,0 +1,8 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Check if `gh` CLI is installed and authenticated.
+ * Returns true if ready, false otherwise.
+ */
+export function checkGhCli(): boolean;

package/api/swizzle/_github.test.mjs

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Unit tests for `checkGhCli()` — the only export of utils/github.mjs.
+ *
+ * `checkGhCli` shells out to `gh auth status` via `execFileSync`. These tests
+ * mock `node:child_process` so they never depend on `gh` being installed or
+ * authenticated in CI, and assert both the success and failure contracts plus
+ * the exact (non-shell, static-arg) invocation — the property that keeps this
+ * helper injection-free.
+ */
+
+import {describe, it, expect, vi, afterEach} from 'vitest';
+import {execFileSync} from 'node:child_process';
+import {checkGhCli} from './_github.mjs';
+
+vi.mock('node:child_process', () => ({execFileSync: vi.fn()}));
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('checkGhCli', () => {
+  it('returns true when `gh auth status` succeeds', () => {
+    vi.mocked(execFileSync).mockReturnValue(Buffer.from(''));
+    expect(checkGhCli()).toBe(true);
+  });
+
+  it('invokes gh with a static, non-shell argument array (no injection surface)', () => {
+    vi.mocked(execFileSync).mockReturnValue(Buffer.from(''));
+    checkGhCli();
+    expect(execFileSync).toHaveBeenCalledTimes(1);
+    expect(execFileSync).toHaveBeenCalledWith('gh', ['auth', 'status'], {
+      stdio: 'ignore',
+    });
+  });
+
+  it('returns false when gh is missing or unauthenticated (throws)', () => {
+    vi.mocked(execFileSync).mockImplementation(() => {
+      throw new Error('command not found: gh');
+    });
+    expect(checkGhCli()).toBe(false);
+  });
+
+  it('swallows a non-zero exit (unauthenticated) and returns false', () => {
+    vi.mocked(execFileSync).mockImplementation(() => {
+      const err = new Error('gh: not logged in');
+      /** @type {any} */ (err).status = 1;
+      throw err;
+    });
+    expect(checkGhCli()).toBe(false);
+  });
+});

package/api/swizzle/copy/copy.d.mts

@@ -0,0 +1,44 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Rewrite relative imports that point outside the component directory to use
+ * the OWNER package's subpaths. Imports within the copied directory (./x) are
+ * left untouched.
+ *
+ * e.g. with ownerPackage '@astryxdesign/core':
+ *      '../theme/tokens.stylex' -> '@astryxdesign/core/theme/tokens.stylex'
+ *      '../utils/mergeProps'     -> '@astryxdesign/core/utils'
+ *      '../../locales/en.json'   -> '@astryxdesign/core/locales/en.json'
+ *      import('../Tooltip/Tooltip') -> import('@astryxdesign/core/Tooltip')
+ *
+ * Most sibling dirs are barrels, so the top-dir collapse (`../utils/x` ->
+ * `<pkg>/utils`) resolves. Two shapes must NOT be collapsed to the top dir:
+ *   - Asset files (`.json`, `.css`): exported by full subpath (e.g.
+ *     `./locales/*.json`, `./reset.css`), and collapsing a two-levels-up
+ *     `../../locales/x.json` would emit the invalid `<pkg>/..`.
+ *   - The theme StyleX token module (`../theme/tokens.stylex`): the StyleX
+ *     compiler needs the real module, which core ships as the dedicated
+ *     `./theme/tokens.stylex` export (the in-repo charts consumer imports it
+ *     by that exact subpath). Other `.stylex` files (e.g. a component-local
+ *     `../Layer/layerAnimations.stylex`) are NOT exported by subpath, so they
+ *     keep the barrel collapse.
+ *
+ * @param {string} content
+ * @param {string} [ownerPackage]
+ */
+export function rewriteImports(content: string, ownerPackage?: string): string;
+/**
+ * Copy one component's source into the consumer project for customization,
+ * rewriting escaping relative imports to the owner package's subpaths.
+ *
+ * @param {string} component bare or XDS-prefixed component name
+ * @param {{cwd?: string, output?: string, package?: string, overwrite?: boolean}} [options]
+ * @returns {Promise<import('../swizzle.type.mjs').SwizzleCopyResponse>}
+ */
+export function swizzleCopy(component: string, options?: {
+    cwd?: string;
+    output?: string;
+    package?: string;
+    overwrite?: boolean;
+}): Promise<import("../swizzle.type.mjs").SwizzleCopyResponse>;

package/api/swizzle/copy/copy.mjs

@@ -16,15 +16,15 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {resolveCore} from '../_adapter.mjs';
-import {assertWithin, PathSafetyError} from '../../../utils/path-safety.mjs';
-import {checkGhCli} from '../../../utils/github.mjs';
-import {Project} from '../../../lib/project.mjs';
+import {assertWithin, sanitizeName, PathSafetyError} from '../../../foundation/fs/path-safety.mjs';
+import {checkGhCli} from '../_github.mjs';
+import {Project} from '../../../foundation/config/project.mjs';
 import {
   CORE_PACKAGE,
   findIntegrationComponentDoc,
   findIntegrationComponentSource,
-} from '../../../lib/component-discovery.mjs';
-import {ERROR_CODES} from '../../../lib/error-codes.mjs';
+} from '../../../foundation/discovery/component-discovery.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {AstryxError} from '../../error.mjs';
 
 /** Default issue tracker for maintainer feedback after swizzling. */
@@ -36,21 +36,54 @@ const DEFAULT_ISSUES_URL = 'https://github.com/facebook/astryx/issues/new';
  * left untouched.
  *
  * e.g. with ownerPackage '@astryxdesign/core':
- *      '../theme/tokens.stylex' -> '@astryxdesign/core/theme'
+ *      '../theme/tokens.stylex' -> '@astryxdesign/core/theme/tokens.stylex'
  *      '../utils/mergeProps'     -> '@astryxdesign/core/utils'
+ *      '../../locales/en.json'   -> '@astryxdesign/core/locales/en.json'
+ *      import('../Tooltip/Tooltip') -> import('@astryxdesign/core/Tooltip')
+ *
+ * Most sibling dirs are barrels, so the top-dir collapse (`../utils/x` ->
+ * `<pkg>/utils`) resolves. Two shapes must NOT be collapsed to the top dir:
+ *   - Asset files (`.json`, `.css`): exported by full subpath (e.g.
+ *     `./locales/*.json`, `./reset.css`), and collapsing a two-levels-up
+ *     `../../locales/x.json` would emit the invalid `<pkg>/..`.
+ *   - The theme StyleX token module (`../theme/tokens.stylex`): the StyleX
+ *     compiler needs the real module, which core ships as the dedicated
+ *     `./theme/tokens.stylex` export (the in-repo charts consumer imports it
+ *     by that exact subpath). Other `.stylex` files (e.g. a component-local
+ *     `../Layer/layerAnimations.stylex`) are NOT exported by subpath, so they
+ *     keep the barrel collapse.
  *
  * @param {string} content
  * @param {string} [ownerPackage]
  */
 export function rewriteImports(content, ownerPackage = CORE_PACKAGE) {
-  return content.replace(
-    /(from\s+['"])(\.\.\/.+?)(['"])/g,
-    (match, prefix, importPath, suffix) => {
-      const parts = importPath.replace(/^\.\.\//, '').split('/');
-      const topDir = parts[0];
-      return `${prefix}${ownerPackage}/${topDir}${suffix}`;
-    },
-  );
+  /** @param {string} importPath */
+  const mapTarget = importPath => {
+    // Strip ALL leading `../` so a two-levels-up path never yields `<pkg>/..`.
+    const rest = importPath.replace(/^(?:\.\.\/)+/, '');
+    const parts = rest.split('/');
+    const last = parts[parts.length - 1];
+    // Asset files are resolved by exact export / wildcard, never a barrel.
+    if (/\.(?:json|css)$/.test(last)) {
+      return `${ownerPackage}/${rest}`;
+    }
+    // The theme token module is a dedicated deep StyleX export.
+    if (parts[0] === 'theme' && /\.stylex(?:\.[cm]?[jt]sx?)?$/.test(last)) {
+      return `${ownerPackage}/${rest}`;
+    }
+    return `${ownerPackage}/${parts[0]}`;
+  };
+  return content
+    .replace(
+      /(from\s+['"])(\.\.\/[^'"]+)(['"])/g,
+      (_m, prefix, importPath, suffix) =>
+        `${prefix}${mapTarget(importPath)}${suffix}`,
+    )
+    .replace(
+      /(import\(\s*['"])(\.\.\/[^'"]+)(['"])/g,
+      (_m, prefix, importPath, suffix) =>
+        `${prefix}${mapTarget(importPath)}${suffix}`,
+    );
 }
 
 /**
@@ -77,7 +110,7 @@ function buildFeedback(component, issuesUrl) {
  * Load the configured integrations + core issues URL for `cwd`, swallowing any
  * config errors so swizzle never hard-fails on a malformed/absent config.
  * @param {string} cwd
- * @returns {Promise<{loadedIntegrations: import('../../../lib/integrations.mjs').LoadedIntegration[], issuesUrl: string|undefined, project: Project|null}>}
+ * @returns {Promise<{loadedIntegrations: import('../../../foundation/integrations/integrations.mjs').LoadedIntegration[], issuesUrl: string|undefined, project: Project|null}>}
  */
 async function loadConfigSafely(cwd) {
   try {
@@ -139,7 +172,7 @@ function isExcludedFromCopy(file) {
  *
  * @param {string} component bare or XDS-prefixed component name
  * @param {{cwd?: string, output?: string, package?: string, overwrite?: boolean}} [options]
- * @returns {Promise<import('../../../types/swizzle').SwizzleCopyResponse>}
+ * @returns {Promise<import('../swizzle.type.mjs').SwizzleCopyResponse>}
  */
 export async function swizzleCopy(component, options = {}) {
   const {
@@ -153,6 +186,19 @@ export async function swizzleCopy(component, options = {}) {
 
   const dirName = component.replace(/^XDS/, '');
 
+  // The component name becomes a path segment in the output dir
+  // (path.join(outputBase, dirName)), so a name containing `..` or a separator
+  // would escape the assertWithin(output) guard. Reject it up front — a real
+  // component name is a bare identifier.
+  try {
+    sanitizeName(dirName, {label: 'component name'});
+  } catch (err) {
+    if (err instanceof PathSafetyError) {
+      throw new AstryxError(err.message, [], ERROR_CODES.ERR_PATH_TRAVERSAL);
+    }
+    throw err;
+  }
+
   const {loadedIntegrations, project} = await loadConfigSafely(cwd);
   const coreIssuesUrl = project
     ? project.issuesUrl({package: CORE_PACKAGE})
@@ -258,7 +304,7 @@ export async function swizzleCopy(component, options = {}) {
   );
   const feedback = buildFeedback(dirName, owner.issuesUrl);
 
-  /** @type {import('../../../types/swizzle').SwizzleCopyResponse['data']} */
+  /** @type {import('../swizzle.type.mjs').SwizzleCopyResponse['data']} */
   const data = {
     component: dirName,
     package: owner.package,