@astryxdesign/cli 0.2.0 → 0.3.0

package/api/hook/hook.type.mjs

@@ -0,0 +1,84 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated types for the `hook` command — source of truth for its JSON
+ * responses (re-exported by the `./json` barrel at `../json/index.d.ts`).
+ *
+ * Detail-level contract for list views (brief < compact < full):
+ *   --detail brief    Names only. Smallest, most scannable. (DEFAULT for --list)
+ *   --detail compact  Names + 1-line description + import path.
+ *   --detail full     Full HookDoc per entry (params, returns, usage, etc.).
+ *
+ * Invocation                                 -> type discriminator
+ * ------------------------------------------------------------------
+ * xds --json hook                           -> hook.list (data.detail='names')
+ * xds --json hook --list                    -> hook.list (data.detail='names')
+ * xds --json hook --category State          -> hook.list (filtered)
+ * xds --json hook --list --detail compact   -> hook.list (data.detail='compact')
+ * xds --json hook --list --detail full      -> hook.list (data.detail='full')
+ * xds --json hook useMediaQuery             -> hook.detail
+ * xds --json hook useMediaQuery --params    -> hook.detail.params
+ * (not found)                               -> CLIError
+ */
+
+// Re-export the authored-doc types from core so the hook leaves reference these
+// colocated aliases here (the leaf @returns reference these rather than reaching
+// into core directly).
+/** @typedef {import('@astryxdesign/cli/authoring').HookDoc} HookDoc */
+/** @typedef {import('@astryxdesign/cli/authoring').HookParamDoc} HookParamDoc */
+
+/**
+ * xds --json hook [--list] [--category X] [--detail names|compact|full]
+ *
+ * The list view emits ONE `hook.list` type across all three detail levels; the
+ * depth is carried in `data.detail` and `data.components` holds the grouped map
+ * whose entry shape depends on that level:
+ *   - 'names'   -> string[]         (hook names only)
+ *   - 'compact' -> HookBriefEntry[] (name + 1-line description + import)
+ *   - 'full'    -> HookDoc[]         (full authored doc per entry)
+ *
+ * @typedef {object} HookListResponse
+ * @property {'hook.list'} type
+ * @property {HookListData} data
+ */
+
+/**
+ * Detail-tagged payload for `hook.list` (discriminated on `detail`).
+ * @typedef {{detail: 'names', components: Record<string, string[]>} | {detail: 'compact', components: Record<string, HookBriefEntry[]>} | {detail: 'full', components: Record<string, HookDoc[]>}} HookListData
+ */
+
+/**
+ * A single entry in a `hook.list` group at `detail: 'compact'`.
+ * @typedef {object} HookBriefEntry
+ * @property {string} name
+ * @property {string} description
+ * @property {string} import
+ */
+
+/**
+ * xds --json hook <name>
+ * @typedef {object} HookDetailResponse
+ * @property {'hook.detail'} type
+ * @property {HookDoc} data
+ */
+
+/**
+ * xds --json hook <name> --params
+ * @typedef {object} HookDetailParamsResponse
+ * @property {'hook.detail.params'} type
+ * @property {HookParamDoc[]} data
+ */
+
+/**
+ * Options for `hook()`.
+ * @typedef {object} HookOptions
+ * @property {string} [cwd]
+ * @property {boolean} [list]
+ * @property {string} [category]
+ * @property {boolean} [params]
+ * @property {'full' | 'compact' | 'brief'} [detail]
+ * @property {string} [lang]
+ * @property {boolean} [zh]
+ */
+
+export {};

package/api/hook/list/list.d.mts

@@ -0,0 +1,19 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @param {object} [options]
+ * @param {string} [options.cwd]
+ * @param {string} [options.category] - When set, list only this category.
+ * @param {'full'|'compact'|'brief'|'names'} [options.detail] - Anything other than 'compact'/'full' renders names only.
+ * @param {boolean} [options.zh]
+ * @param {string|null} [options.lang]
+ * @returns {Promise<import('../hook.type.mjs').HookListResponse>}
+ */
+export function list({ cwd, category, detail, zh, lang }?: {
+    cwd?: string | undefined;
+    category?: string | undefined;
+    detail?: "compact" | "names" | "full" | "brief" | undefined;
+    zh?: boolean | undefined;
+    lang?: string | null | undefined;
+}): Promise<import("../hook.type.mjs").HookListResponse>;

package/api/hook/list/list.mjs

@@ -13,10 +13,10 @@
  * @position api/hook/list/list.mjs — dispatched from ../hook.mjs
  */
 
-import {discoverHooks, findHookDoc} from '../../../lib/hook-discovery.mjs';
-import {loadDocs} from '../../../lib/component-loader.mjs';
+import {discoverHooks, findHookDoc} from '../../../foundation/discovery/hook-discovery.mjs';
+import {loadDocs} from '../../../foundation/discovery/component-loader.mjs';
 import {AstryxError} from '../../error.mjs';
-import {ERROR_CODES} from '../../../lib/error-codes.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {resolveCoreDir} from '../_adapter.mjs';
 
 /**
@@ -26,7 +26,7 @@ import {resolveCoreDir} from '../_adapter.mjs';
  * @param {'full'|'compact'|'brief'|'names'} [options.detail] - Anything other than 'compact'/'full' renders names only.
  * @param {boolean} [options.zh]
  * @param {string|null} [options.lang]
- * @returns {Promise<import('../../../types/hook').HookListResponse>}
+ * @returns {Promise<import('../hook.type.mjs').HookListResponse>}
  */
 export async function list({cwd = process.cwd(), category, detail = 'names', zh = false, lang = null} = {}) {
   const coreDir = resolveCoreDir(cwd);
@@ -45,7 +45,7 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
     }
 
     if (detail === 'compact') {
-      /** @type {import('../../../types/hook').HookBriefEntry[]} */
+      /** @type {import('../hook.type.mjs').HookBriefEntry[]} */
       const entries = [];
       for (const hookName of match[1]) {
         const docPath = findHookDoc(coreDir, hookName);
@@ -68,7 +68,7 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
     }
 
     if (detail === 'full') {
-      /** @type {import('../../../types/hook').HookDoc[]} */
+      /** @type {import('../hook.type.mjs').HookDoc[]} */
       const entries = [];
       for (const hookName of match[1]) {
         const docPath = findHookDoc(coreDir, hookName);
@@ -76,10 +76,10 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
           try {
             entries.push(await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang})));
           } catch {
-            entries.push(/** @type {import('../../../types/hook').HookDoc} */ ({name: hookName}));
+            entries.push(/** @type {import('../hook.type.mjs').HookDoc} */ ({name: hookName}));
           }
         } else {
-          entries.push(/** @type {import('../../../types/hook').HookDoc} */ ({name: hookName}));
+          entries.push(/** @type {import('../hook.type.mjs').HookDoc} */ ({name: hookName}));
         }
       }
       return {type: 'hook.list', data: {detail: 'full', components: {[match[0]]: entries}}};
@@ -91,7 +91,7 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
 
   // All hooks
   if (detail === 'compact') {
-    /** @type {Record<string, import('../../../types/hook').HookBriefEntry[]>} */
+    /** @type {Record<string, import('../hook.type.mjs').HookBriefEntry[]>} */
     const result = {};
     for (const [cat, hookNames] of Object.entries(hooks)) {
       result[cat] = [];
@@ -117,7 +117,7 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
   }
 
   if (detail === 'full') {
-    /** @type {Record<string, import('../../../types/hook').HookDoc[]>} */
+    /** @type {Record<string, import('../hook.type.mjs').HookDoc[]>} */
     const result = {};
     for (const [cat, hookNames] of Object.entries(hooks)) {
       result[cat] = [];
@@ -127,10 +127,10 @@ export async function list({cwd = process.cwd(), category, detail = 'names', zh
           try {
             result[cat].push(await loadDocs(docPath, /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang})));
           } catch {
-            result[cat].push(/** @type {import('../../../types/hook').HookDoc} */ ({name: hookName}));
+            result[cat].push(/** @type {import('../hook.type.mjs').HookDoc} */ ({name: hookName}));
           }
         } else {
-          result[cat].push(/** @type {import('../../../types/hook').HookDoc} */ ({name: hookName}));
+          result[cat].push(/** @type {import('../hook.type.mjs').HookDoc} */ ({name: hookName}));
         }
       }
     }

package/api/index.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.
+
+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 { hook } from "./hook/hook.mjs";
+export { search } from "./search/search.mjs";
+export { build } from "./build/build.mjs";
+export { swizzle } from "./swizzle/swizzle.mjs";
+export { upgrade } from "./upgrade/upgrade.mjs";
+export { init } from "./init/init.mjs";
+export { doctor } from "./doctor/doctor.mjs";
+export { AstryxError } from "./error.mjs";
+export { logger } from "./logger.mjs";
+export * from "./component/component.type.mjs";
+export * from "./docs/docs.type.mjs";
+export * from "./blog/blog.type.mjs";
+export * from "./discover/discover.type.mjs";
+export * from "./template/template.type.mjs";
+export * from "./theme/theme.type.mjs";
+export * from "./hook/hook.type.mjs";
+export * from "./search/search.type.mjs";
+export * from "./build/build.type.mjs";
+export * from "./swizzle/swizzle.type.mjs";
+export * from "./upgrade/upgrade.type.mjs";
+export * from "./init/init.type.mjs";
+export * from "./doctor/doctor.type.mjs";
+export * from "./layout/layout.type.mjs";
+export * from "./integration/validate-integration.type.mjs";
+export type Logger = import("./logger.mjs").Logger;
+export { themeBuild, themeAdd, themeList, listThemes } from "./theme/theme.mjs";
+export { layoutExpand, layoutCheck, layoutGrammar } from "./layout/layout.mjs";
+export { validateIntegration, summarizeIssues } from "./integration/validate-integration.mjs";

package/api/index.mjs

@@ -19,6 +19,7 @@
  * // { type: 'hook.detail', data: { name: 'useMediaQuery', ... } }
  */
 
+// ── Functions (runtime) ──────────────────────────────────────────────
 export {component} from './component/component.mjs';
 export {docs} from './docs/docs.mjs';
 export {blog} from './blog/blog.mjs';
@@ -38,3 +39,30 @@ export {
   summarizeIssues,
 } from './integration/validate-integration.mjs';
 export {AstryxError} from './error.mjs';
+// The one shared logger: the `logger` instance side-effecting commands write
+// through, plus its generated `Logger` type. Part of the public surface so an
+// embedder can enable/inspect output.
+export {logger} from './logger.mjs';
+/**
+ * @typedef {import('./logger.mjs').Logger} Logger
+ */
+
+// ── Types (re-exported from each command's colocated `.type.mjs`) ─────
+// Runtime no-ops (the .type.mjs files are `export {}`); tsc carries these
+// through to the generated api/index.d.mts so the public type surface exposes
+// every command's Options + response types by name.
+export * from './component/component.type.mjs';
+export * from './docs/docs.type.mjs';
+export * from './blog/blog.type.mjs';
+export * from './discover/discover.type.mjs';
+export * from './template/template.type.mjs';
+export * from './theme/theme.type.mjs';
+export * from './hook/hook.type.mjs';
+export * from './search/search.type.mjs';
+export * from './build/build.type.mjs';
+export * from './swizzle/swizzle.type.mjs';
+export * from './upgrade/upgrade.type.mjs';
+export * from './init/init.type.mjs';
+export * from './doctor/doctor.type.mjs';
+export * from './layout/layout.type.mjs';
+export * from './integration/validate-integration.type.mjs';

package/api/init/init.d.mts

@@ -0,0 +1,37 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Re-exported types so callers can keep referencing them off the init barrel
+ * (e.g. cli/commands/init.mjs uses `import('../../api/init/init.mjs').InitOptions`).
+ * The canonical shapes stay colocated in api/init/init.type.mjs.
+ * @typedef {import('./init.type.mjs').InitOptions} InitOptions
+ * @typedef {import('./init.type.mjs').InitRunData} InitRunData
+ */
+/**
+ * Run the non-interactive init flow. Dispatches to the remove leaf when
+ * `--remove-agents` is set, otherwise to the install (run) leaf, and returns
+ * that leaf's receipt. Progress is emitted through `logger` (silent by
+ * default); unknown feature or template names throw AstryxError with a stable
+ * code.
+ *
+ * @param {InitOptions} [options]
+ * @param {{cwd?: string}} [ctx]
+ * @returns {Promise<import('./init.type.mjs').InitRunResponse | import('./init.type.mjs').InitRemoveResponse>}
+ */
+export function init(options?: InitOptions, { cwd }?: {
+    cwd?: string;
+}): Promise<import("./init.type.mjs").InitRunResponse | import("./init.type.mjs").InitRemoveResponse>;
+export { getNextSteps } from "./run/run.mjs";
+/**
+ * Re-exported types so callers can keep referencing them off the init barrel
+ * (e.g. cli/commands/init.mjs uses `import('../../api/init/init.mjs').InitOptions`).
+ * The canonical shapes stay colocated in api/init/init.type.mjs.
+ */
+export type InitOptions = import("./init.type.mjs").InitOptions;
+/**
+ * Re-exported types so callers can keep referencing them off the init barrel
+ * (e.g. cli/commands/init.mjs uses `import('../../api/init/init.mjs').InitOptions`).
+ * The canonical shapes stay colocated in api/init/init.type.mjs.
+ */
+export type InitRunData = import("./init.type.mjs").InitRunData;

package/api/init/init.mjs

@@ -12,26 +12,21 @@
  *   - `init.remove` (remove/remove.mjs) — the `--remove-agents` path
  *
  * This module also re-exports the leaf symbols the CLI + tests import by name
- * (`getNextSteps`, `noopInitLogger`) so api/index.mjs, the command handler
+ * (`getNextSteps`) so api/index.mjs, the command handler
  * (cli/commands/init.mjs), and the test suite stay unchanged.
  */
 
 import {run} from './run/run.mjs';
 import {remove} from './remove/remove.mjs';
-import {noopInitLogger} from './_adapter.mjs';
 
 export {getNextSteps} from './run/run.mjs';
-export {noopInitLogger} from './_adapter.mjs';
 
 /**
  * Re-exported types so callers can keep referencing them off the init barrel
- * (e.g. cli/commands/init.mjs uses `import('../../api/init/init.mjs').InitOptions`
- * and `.InitLogger`). The canonical shapes stay central in types/api.d.ts +
- * types/init.d.ts; these aliases just preserve the barrel's original type
- * surface after the split.
- * @typedef {import('../../types/api').InitOptions} InitOptions
- * @typedef {import('./_adapter.mjs').InitLogger} InitLogger
- * @typedef {import('../../types/init').InitRunData} InitRunData
+ * (e.g. cli/commands/init.mjs uses `import('../../api/init/init.mjs').InitOptions`).
+ * The canonical shapes stay colocated in api/init/init.type.mjs.
+ * @typedef {import('./init.type.mjs').InitOptions} InitOptions
+ * @typedef {import('./init.type.mjs').InitRunData} InitRunData
  */
 
 /**
@@ -42,12 +37,12 @@ export {noopInitLogger} from './_adapter.mjs';
  * code.
  *
  * @param {InitOptions} [options]
- * @param {{cwd?: string, logger?: InitLogger}} [ctx]
- * @returns {Promise<import('../../types/init').InitRunResponse | import('../../types/init').InitRemoveResponse>}
+ * @param {{cwd?: string}} [ctx]
+ * @returns {Promise<import('./init.type.mjs').InitRunResponse | import('./init.type.mjs').InitRemoveResponse>}
  */
-export async function init(options = {}, {cwd = process.cwd(), logger = noopInitLogger} = {}) {
+export async function init(options = {}, {cwd = process.cwd()} = {}) {
   if (options.removeAgents) {
-    return remove({cwd, logger});
+    return remove({cwd});
   }
-  return run(options, {cwd, logger});
+  return run(options, {cwd});
 }

package/api/init/init.test.mjs

@@ -13,8 +13,9 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import {init, getNextSteps} from './init.mjs';
+import {logger} from '../logger.mjs';
 import {AstryxError} from '../error.mjs';
-import {ERROR_CODES} from '../../lib/error-codes.mjs';
+import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 
 const MARKER_START = '<!-- ASTRYX:START -->';
 
@@ -135,11 +136,19 @@ describe('init() — logger', () => {
     expect(err).toEqual([]);
   });
 
-  it('emits the install line + full next-steps through the injected logger', async () => {
+  it('emits the install line + full next-steps through the shared logger', async () => {
     /** @type {string[]} */
     const lines = [];
-    const logger = {log: m => lines.push(m ?? ''), error: m => lines.push(`ERR:${m}`)};
-    await init({}, {cwd: tmpDir, logger});
+    const logSpy = vi.spyOn(console, 'log').mockImplementation((...a) => lines.push(a.join(' ')));
+    const errSpy = vi.spyOn(console, 'error').mockImplementation((...a) => lines.push(`ERR:${a.join(' ')}`));
+    logger.setSilent(false);
+    try {
+      await init({}, {cwd: tmpDir});
+    } finally {
+      logger.setSilent(true);
+      logSpy.mockRestore();
+      errSpy.mockRestore();
+    }
     const text = lines.join('\n');
     expect(text).toContain('✓ AI agent docs installed → AGENTS.md');
     expect(text).toContain('  Next steps:');
@@ -147,3 +156,28 @@ describe('init() — logger', () => {
     expect(text).toContain(getNextSteps('npx astryx')[2].slice(0, 20));
   });
 });
+
+describe('init() — write-path safety', () => {
+  it('template scaffold refuses to clobber an existing page.tsx', async () => {
+    const dest = path.join(tmpDir, 'src', 'pages', 'blank');
+    fs.mkdirSync(dest, {recursive: true});
+    fs.writeFileSync(path.join(dest, 'page.tsx'), 'MY EXISTING FILE');
+    await expect(
+      init({features: 'template', templateName: 'blank'}, {cwd: tmpDir}),
+    ).rejects.toMatchObject({code: ERROR_CODES.ERR_FILE_EXISTS});
+    // user's file is untouched
+    expect(fs.readFileSync(path.join(dest, 'page.tsx'), 'utf8')).toBe('MY EXISTING FILE');
+  });
+
+  it('throws ERR_UNKNOWN_AGENT for an unknown --agent value', async () => {
+    await expect(
+      init({features: 'agents', agent: 'claud'}, {cwd: tmpDir}),
+    ).rejects.toMatchObject({code: ERROR_CODES.ERR_UNKNOWN_AGENT});
+  });
+
+  it('rejects a traversal templateName before any write (ERR_UNKNOWN_TEMPLATE)', async () => {
+    await expect(
+      init({features: 'template', templateName: '../../etc/evil'}, {cwd: tmpDir}),
+    ).rejects.toMatchObject({code: ERROR_CODES.ERR_UNKNOWN_TEMPLATE});
+  });
+});

package/api/init/init.type.d.mts

@@ -0,0 +1,79 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+export type InitRunData = {
+    /**
+     * `default` (no flags) or `features` (--features/--all).
+     */
+    mode: "default" | "features";
+    /**
+     * Features that were run, in order.
+     */
+    features: string[];
+    /**
+     * Agent-doc files written (empty if agents weren't run or install failed).
+     */
+    docsWritten: string[];
+    /**
+     * Soft agent-docs failure, if any. `path-safety` also implies a non-zero exit.
+     */
+    docsError: {
+        kind: "path-safety" | "install-failed";
+        message?: string;
+    } | null;
+    /**
+     * Whether theme guidance was emitted.
+     */
+    theme: boolean;
+    /**
+     * Template outcome (`workflow` is the CLI default; `created`/`skipped` are programmatic).
+     */
+    template: "workflow" | "created" | "skipped" | null;
+    /**
+     * Relative output path when `template === 'created'`.
+     */
+    templatePath: string | null;
+    /**
+     * Whether the getting-started "Next steps" were emitted (default mode).
+     */
+    nextSteps: boolean;
+};
+export type InitRunResponse = {
+    type: "init.run";
+    data: InitRunData;
+};
+export type InitRemoveResponse = {
+    type: "init.remove";
+    data: {
+        removed: true;
+    };
+};
+/**
+ * Options for `init()`.
+ */
+export type InitOptions = {
+    /**
+     * Comma-separated features to install (agents, theme, template).
+     */
+    features?: string | undefined;
+    /**
+     * Install all features.
+     */
+    all?: boolean | undefined;
+    /**
+     * Remove the managed agent-docs block instead of installing.
+     */
+    removeAgents?: boolean | undefined;
+    /**
+     * Agent preset: claude, cursor, codex, hermes, all.
+     */
+    agent?: string | undefined;
+    /**
+     * Explicit agent-docs file path(s).
+     */
+    agentDocsPath?: string | string[] | undefined;
+    /**
+     * Scaffold a named page template (programmatic only; the CLI never sets it).
+     */
+    templateName?: string | undefined;
+};

package/api/init/init.type.mjs

@@ -0,0 +1,44 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated types for the `init` command — source of truth for the init
+ * API response receipts and options. Re-exported by types/init.d.ts; the public
+ * `./api` type surface regenerates from this JSDoc.
+ */
+
+/**
+ * @typedef {object} InitRunData
+ * @property {'default' | 'features'} mode `default` (no flags) or `features` (--features/--all).
+ * @property {string[]} features Features that were run, in order.
+ * @property {string[]} docsWritten Agent-doc files written (empty if agents weren't run or install failed).
+ * @property {{kind: 'path-safety' | 'install-failed', message?: string} | null} docsError Soft agent-docs failure, if any. `path-safety` also implies a non-zero exit.
+ * @property {boolean} theme Whether theme guidance was emitted.
+ * @property {'workflow' | 'created' | 'skipped' | null} template Template outcome (`workflow` is the CLI default; `created`/`skipped` are programmatic).
+ * @property {string | null} templatePath Relative output path when `template === 'created'`.
+ * @property {boolean} nextSteps Whether the getting-started "Next steps" were emitted (default mode).
+ */
+
+/**
+ * @typedef {object} InitRunResponse
+ * @property {'init.run'} type
+ * @property {InitRunData} data
+ */
+
+/**
+ * @typedef {object} InitRemoveResponse
+ * @property {'init.remove'} type
+ * @property {{removed: true}} data
+ */
+
+/**
+ * Options for `init()`.
+ * @typedef {object} InitOptions
+ * @property {string} [features] Comma-separated features to install (agents, theme, template).
+ * @property {boolean} [all] Install all features.
+ * @property {boolean} [removeAgents] Remove the managed agent-docs block instead of installing.
+ * @property {string} [agent] Agent preset: claude, cursor, codex, hermes, all.
+ * @property {string | string[]} [agentDocsPath] Explicit agent-docs file path(s).
+ * @property {string} [templateName] Scaffold a named page template (programmatic only; the CLI never sets it).
+ */
+
+export {};

package/api/init/remove/remove.d.mts

@@ -0,0 +1,13 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Remove the managed agent-docs block and return an `init.remove` receipt.
+ * Progress is emitted through the shared `logger` (silent by default).
+ *
+ * @param {{cwd?: string}} [ctx]
+ * @returns {Promise<import('../init.type.mjs').InitRemoveResponse>}
+ */
+export function remove({ cwd }?: {
+    cwd?: string;
+}): Promise<import("../init.type.mjs").InitRemoveResponse>;

package/api/init/remove/remove.mjs

@@ -5,24 +5,24 @@
  *
  * `remove(ctx)` deletes the managed agent-docs block from every agent-doc file
  * and returns an `init.remove` receipt. The removal engine lives in
- * lib/agent-docs; this leaf only wires the cwd + the injected logger.
+ * lib/agent-docs; this leaf only wires the cwd.
  *
  * Note: removeAgentDocs() still logs its own per-file lines via humanLog
  * (shared lib behavior) — so a programmatic remove is not perfectly silent yet.
  * Threading a logger through agent-docs is a separate cleanup.
  */
 
-import {removeAgentDocs} from '../../../lib/agent-docs/agent-docs.mjs';
-import {noopInitLogger} from '../_adapter.mjs';
+import {removeAgentDocs} from '../../../foundation/agent-docs/agent-docs.mjs';
+import {logger} from '../../logger.mjs';
 
 /**
  * Remove the managed agent-docs block and return an `init.remove` receipt.
- * Progress is emitted through `logger` (silent by default).
+ * Progress is emitted through the shared `logger` (silent by default).
  *
- * @param {{cwd?: string, logger?: import('../_adapter.mjs').InitLogger}} [ctx]
- * @returns {Promise<import('../../../types/init').InitRemoveResponse>}
+ * @param {{cwd?: string}} [ctx]
+ * @returns {Promise<import('../init.type.mjs').InitRemoveResponse>}
  */
-export async function remove({cwd = process.cwd(), logger = noopInitLogger} = {}) {
+export async function remove({cwd = process.cwd()} = {}) {
   removeAgentDocs(cwd);
   logger.log('✓ AI agent docs removed.');
   return {type: 'init.remove', data: {removed: true}};

package/api/init/run/run.d.mts

@@ -0,0 +1,30 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Build the "Next steps" lines printed at the end of `astryx init`.
+ *
+ * Theme guidance must match the runtime recommendation emitted by core's
+ * <Theme> component (packages/core/src/theme/Theme.tsx): the pre-built theme
+ * path (`/built` import + `theme.css`) plus the base CSS import, so users
+ * don't end up with an unstyled app or the slower runtime style-injection
+ * path. See https://github.com/facebook/astryx/issues/3080.
+ *
+ * @param {string} invocation install-aware CLI invocation stem (e.g. `npx astryx`, `pnpm exec astryx`, or `npx @astryxdesign/cli` for one-off runs)
+ * @returns {string[]} ordered list of human-facing lines
+ */
+export function getNextSteps(invocation: string): string[];
+/**
+ * Run the install path of the non-interactive init flow (the default no-flags
+ * install plus `--features` / `--all`). Performs the side effects (agent-docs
+ * install, template scaffold) and returns an `init.run` receipt. Progress is
+ * emitted through `logger` (silent by default); unknown feature or template
+ * names throw AstryxError with a stable code.
+ *
+ * @param {import('../init.type.mjs').InitOptions} [options]
+ * @param {{cwd?: string}} [ctx]
+ * @returns {Promise<import('../init.type.mjs').InitRunResponse>}
+ */
+export function run(options?: import("../init.type.mjs").InitOptions, { cwd }?: {
+    cwd?: string;
+}): Promise<import("../init.type.mjs").InitRunResponse>;