Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(cli): add `template get --id` command with configurable hook (#1327)

Joeyd2b9b4147668
diff --git a/packages/cli/src/api/template.mjs b/packages/cli/src/api/template.mjs
index 724d2aa2cb..dc48b9b442 100644
--- a/packages/cli/src/api/template.mjs
+++ b/packages/cli/src/api/template.mjs
@@ -6,6 +6,7 @@ import * as fs from 'node:fs';
import * as path from 'node:path';
import {CLI_ROOT} from '../utils/paths.mjs';
import {XDSError} from './error.mjs';
+import {loadConfig} from '../lib/config.mjs';
const TEMPLATES_DIR = path.join(CLI_ROOT, 'templates');
@@ -168,6 +169,59 @@ function extractSkeleton(source) {
return out.filter(l => l.trim()).join('\n');
}
+/**
+ * Fetch a template by ID using the `template.get` hook in xds.config.mjs.
+ * @param {string} id
+ * @param {object} [options]
+ * @param {string} [options.cwd]
+ * @returns {Promise<{type: 'template.get', data: {id: string, source: string}}>}
+ */
+export async function getTemplateById(id, options = {}) {
+ const {cwd = process.cwd()} = options;
+ const config = await loadConfig(cwd);
+
+ const getter = config.template?.get;
+ if (typeof getter !== 'function') {
+ throw new XDSError(
+ 'Template fetching by ID is not configured.\n' +
+ 'Add a template.get function to xds.config.mjs:\n\n' +
+ ' export default {\n' +
+ ' template: {\n' +
+ " get: async (id) => { /* return template source string */ },\n" +
+ ' },\n' +
+ ' };',
+ );
+ }
+
+ let source;
+ try {
+ source = await getter(id);
+ } catch (err) {
+ const detail = err instanceof Error ? err.message : String(err);
+ throw new XDSError(`template.get("${id}") threw an error: ${detail}`);
+ }
+
+ if (source == null) {
+ throw new XDSError(
+ `template.get("${id}") returned ${source} — no template found for that ID`,
+ );
+ }
+
+ if (typeof source !== 'string') {
+ throw new XDSError(
+ `template.get("${id}") must return a string, got ${typeof source}`,
+ );
+ }
+
+ if (source.trim() === '') {
+ throw new XDSError(
+ `template.get("${id}") returned an empty string`,
+ );
+ }
+
+ return {type: 'template.get', data: {id, source}};
+}
+
/**
* @param {string} [name]
* @param {object} [options]
diff --git a/packages/cli/src/commands/template.mjs b/packages/cli/src/commands/template.mjs
index 7448c47f52..850944d7aa 100644
--- a/packages/cli/src/commands/template.mjs
+++ b/packages/cli/src/commands/template.mjs
@@ -5,12 +5,12 @@
import * as path from 'node:path';
import {CLI_ROOT} from '../utils/paths.mjs';
import {jsonOut, jsonError} from '../lib/json.mjs';
-import {template as templateApi} from '../api/template.mjs';
+import {template as templateApi, getTemplateById} from '../api/template.mjs';
-export {discoverTemplates, listTemplates} from '../api/template.mjs';
+export {discoverTemplates, listTemplates, getTemplateById} from '../api/template.mjs';
export function registerTemplate(program) {
- program
+ const templateCmd = program
.command('template [name] [path]')
.description('Inject a page template')
.option('--list', 'List available templates with component compositions')
@@ -71,4 +71,25 @@ export function registerTemplate(program) {
}
}
});
+
+ templateCmd
+ .command('get')
+ .description('Fetch a template by ID via the xds.config.mjs hook')
+ .requiredOption('--id <id>', 'Template identifier to fetch')
+ .action(async (options) => {
+ const json = program.opts().json || false;
+
+ let result;
+ try {
+ result = await getTemplateById(options.id, {cwd: process.cwd()});
+ } catch (e) {
+ if (json) return jsonError(e.message, e.suggestions);
+ console.error(`Error: ${e.message}`);
+ process.exit(1);
+ }
+
+ if (json) return jsonOut(result.type, result.data);
+
+ console.log(result.data.source);
+ });
}
diff --git a/packages/cli/src/types/api.d.ts b/packages/cli/src/types/api.d.ts
index 4a96a7e407..6ba838fa8a 100644
--- a/packages/cli/src/types/api.d.ts
+++ b/packages/cli/src/types/api.d.ts
@@ -28,6 +28,7 @@ import type {
TemplateShowResponse,
TemplateSkeletonResponse,
TemplateCopyResponse,
+ TemplateGetResponse,
} from './template';
/** Structured API error with optional suggestions. */
@@ -123,3 +124,8 @@ export declare function template(
name?: string,
options?: TemplateOptions,
): Promise<TemplateResult>;
+
+export declare function getTemplateById(
+ id: string,
+ options?: {cwd?: string},
+): Promise<TemplateGetResponse>;
diff --git a/packages/cli/src/types/base.d.ts b/packages/cli/src/types/base.d.ts
index f42e433755..b16160bb40 100644
--- a/packages/cli/src/types/base.d.ts
+++ b/packages/cli/src/types/base.d.ts
@@ -24,7 +24,13 @@ import type {
DocsDetailResponse,
DocsDetailSectionResponse,
} from './docs';
-import type {TemplateListResponse, TemplateCopyResponse} from './template';
+import type {
+ TemplateListResponse,
+ TemplateShowResponse,
+ TemplateSkeletonResponse,
+ TemplateCopyResponse,
+ TemplateGetResponse,
+} from './template';
import type {SwizzleListResponse, SwizzleCopyResponse} from './swizzle';
import type {ThemeBuildResponse} from './theme';
import type {UpgradeListResponse, UpgradeRunResponse} from './upgrade';
@@ -62,7 +68,10 @@ export type CLIAnyResponse =
| DocsDetailResponse
| DocsDetailSectionResponse
| TemplateListResponse
+ | TemplateShowResponse
+ | TemplateSkeletonResponse
| TemplateCopyResponse
+ | TemplateGetResponse
| SwizzleListResponse
| SwizzleCopyResponse
| ThemeBuildResponse
diff --git a/packages/cli/src/types/template.d.ts b/packages/cli/src/types/template.d.ts
index 75070e3925..6617858d11 100644
--- a/packages/cli/src/types/template.d.ts
+++ b/packages/cli/src/types/template.d.ts
@@ -51,3 +51,9 @@ export interface TemplateCopyResponse {
type: 'template.copy';
data: {template: string; outputDir: string; filesCopied: number};
}
+
+/** xds --json template get --id <id> */
+export interface TemplateGetResponse {
+ type: 'template.get';
+ data: {id: string; source: string};
+}