Skip to content

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

TypeScript

feat: integration add theme --from (#6960)

Joey1db06ac17405
diff --git a/.changeset/integration-add-theme-from.md b/.changeset/integration-add-theme-from.md
new file mode 100644
index 0000000000..22849ce083
--- /dev/null
+++ b/.changeset/integration-add-theme-from.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[feat] `integration add theme --from <base>` forks an existing theme as the starting point instead of a blank scaffold. The new theme copies the base's source files — renamed and rewritten for the new slug — with no link back. Use `--from` when you want to change a lot; for a small change that stays linked, use `extends` in `defineTheme`.
+
+@josephfarina
diff --git a/packages/cli/api/integration/add-contribution.mjs b/packages/cli/api/integration/add-contribution.mjs
index d355d8ca17..05310b3b4b 100644
--- a/packages/cli/api/integration/add-contribution.mjs
+++ b/packages/cli/api/integration/add-contribution.mjs
@@ -1211,7 +1211,7 @@ const KIND_OPTIONS = {
template: new Set(['cwd', 'dryRun', 'templateType']),
codemod: new Set(['cwd', 'dryRun', 'to']),
'agent-doc': new Set(['cwd', 'dryRun']),
- theme: new Set(['cwd', 'dryRun']),
+ theme: new Set(['cwd', 'dryRun', 'from']),
};
/**
@@ -1238,7 +1238,7 @@ function validateKindOptions(kind, options) {
*
* @param {'component'|'doc'|'template'|'codemod'|'agent-doc'|'theme'} kind
* @param {string} name
- * @param {{cwd?: string, dryRun?: boolean, templateType?: 'page'|'block', to?: string, replaces?: string, extends?: string, parent?: string}} [options]
+ * @param {{cwd?: string, dryRun?: boolean, templateType?: 'page'|'block', to?: string, replaces?: string, extends?: string, parent?: string, from?: string}} [options]
* @returns {Promise<import('./integration-authoring.type.mjs').IntegrationAddResponse>}
*/
export async function integrationAdd(kind, name, options = {}) {
@@ -1270,6 +1270,10 @@ export async function integrationAdd(kind, name, options = {}) {
case 'agent-doc':
return integrationAddAgentDoc(name, options);
case 'theme':
- return integrationAddTheme(name, options);
+ return integrationAddTheme(name, {
+ cwd: options.cwd,
+ dryRun: options.dryRun,
+ from: options.from,
+ });
}
}
diff --git a/packages/cli/api/integration/add-theme.mjs b/packages/cli/api/integration/add-theme.mjs
index d26fba974a..54cdab3794 100644
--- a/packages/cli/api/integration/add-theme.mjs
+++ b/packages/cli/api/integration/add-theme.mjs
@@ -4,6 +4,9 @@
* @file `astryx integration add theme` — scaffold one strongly typed,
* same-stem source/descriptor pair into an integration package and declare the
* themes root on first use.
+ *
+ * `--from <base>` forks an existing theme's source files as the starting point
+ * instead of writing a blank `defineTheme` skeleton.
*/
import * as fs from 'node:fs';
@@ -15,7 +18,10 @@ import {
PathSafetyError,
sanitizeName,
} from '../../foundation/fs/path-safety.mjs';
-import {discoverThemeDirectory} from '../../foundation/discovery/theme-discovery.mjs';
+import {
+ discoverBundledThemes,
+ discoverThemeDirectory,
+} from '../../foundation/discovery/theme-discovery.mjs';
import {
findLocalIntegrationManifestOrNull,
IntegrationRootConflictError,
@@ -29,6 +35,7 @@ import {
themesCliProblem,
withCliPeer,
} from '../../foundation/integrations/cli-requirement.mjs';
+import {stripCopyrightHeader} from '../../foundation/text/copyright-header.mjs';
import {
applyWrites,
findPackageDir,
@@ -70,6 +77,7 @@ function themeIdentity(slug) {
.join(' ');
return {
slug,
+ identifier,
displayName,
exportName: `${identifier}Theme`,
entry: `${identifier}Theme.ts`,
@@ -93,6 +101,182 @@ function themeDescriptor(identity) {
});
}
+// ── --from: resolve and fork a base theme ───────────────────────────
+
+/**
+ * Resolve a theme slug to its discovered record, searching the bundled themes
+ * and the package's own themes root (when it has one).
+ * @param {string} slug
+ * @param {string} packageDir
+ * @param {string} owner
+ * @param {string | undefined} themesRoot resolved absolute themes root, if any
+ * @returns {import('../../foundation/discovery/theme-discovery.mjs').DiscoveredTheme}
+ */
+function resolveBaseTheme(slug, packageDir, owner, themesRoot) {
+ const normalized = slug.toLowerCase();
+
+ /** @type {import('../../foundation/discovery/theme-discovery.mjs').DiscoveredTheme[]} */
+ let candidates = [];
+ try {
+ candidates = discoverBundledThemes();
+ } catch {
+ // Bundled themes unavailable — not fatal, package themes may suffice.
+ }
+
+ // Also check the package's own themes root.
+ if (themesRoot && fs.existsSync(themesRoot)) {
+ try {
+ candidates = [...candidates, ...discoverThemeDirectory(themesRoot, owner)];
+ } catch {
+ // A broken local root is not the caller's problem here.
+ }
+ }
+
+ const match = candidates.find(t => t.slug.toLowerCase() === normalized);
+ if (!match) {
+ throw new AstryxError(
+ `Unknown base theme "${slug}". Available themes: ${candidates.map(t => t.slug).join(', ') || '(none)'}.`,
+ candidates.map(t => ({
+ name: t.slug,
+ reason: t.bundled ? 'bundled theme' : `provided by ${t.package}`,
+ })),
+ ERROR_CODES.ERR_UNKNOWN_THEME,
+ );
+ }
+ return match;
+}
+
+/**
+ * Rename a file from the base theme's namespace to the new theme's namespace.
+ * Files whose name starts with the base identifier get the new identifier;
+ * others keep their name as-is.
+ * @param {string} file POSIX relative path inside the theme directory
+ * @param {string} baseIdentifier
+ * @param {string} newIdentifier
+ * @returns {string}
+ */
+function renameThemeFile(file, baseIdentifier, newIdentifier) {
+ const basename = path.posix.basename(file);
+ const dir = path.posix.dirname(file);
+ if (!basename.startsWith(baseIdentifier)) return file;
+ const renamed = newIdentifier + basename.slice(baseIdentifier.length);
+ return dir === '.' ? renamed : `${dir}/${renamed}`;
+}
+
+/**
+ * Rewrite a source file's contents from the base theme's names to the new
+ * theme's names. This replaces:
+ * 1. Identifier prefixes (camelCase variables, import paths): baseIdentifier
+ * followed by an uppercase letter.
+ * 2. The theme slug in string literals: 'baseSlug' → 'newSlug' and
+ * 'astryx-baseSlug' → 'astryx-newSlug'.
+ * 3. CSS custom properties scoped to the theme: --astryx-theme-baseSlug-.
+ * @param {string} source
+ * @param {string} baseSlug
+ * @param {string} baseIdentifier
+ * @param {string} newSlug
+ * @param {string} newIdentifier
+ * @returns {string}
+ */
+function rewriteThemeSource(
+ source,
+ baseSlug,
+ baseIdentifier,
+ newSlug,
+ newIdentifier,
+) {
+ let result = source;
+ // 1. Identifier prefixes: neutralPalettes → oceanPalettes, neutralTheme → oceanTheme
+ const identRe = new RegExp(`${escapeRegExp(baseIdentifier)}(?=[A-Z])`, 'gu');
+ result = result.replace(identRe, newIdentifier);
+ // 2. String-literal theme names
+ result = result.replace(
+ new RegExp(`'astryx-${escapeRegExp(baseSlug)}'`, 'gu'),
+ `'astryx-${newSlug}'`,
+ );
+ result = result.replace(
+ new RegExp(`'${escapeRegExp(baseSlug)}'`, 'gu'),
+ `'${newSlug}'`,
+ );
+ // 3. CSS custom properties scoped to the base theme
+ result = result.replace(
+ new RegExp(
+ `--astryx-theme-${escapeRegExp(baseSlug)}-`,
+ 'gu',
+ ),
+ `--astryx-theme-${newSlug}-`,
+ );
+ return result;
+}
+
+/** @param {string} s */
+function escapeRegExp(s) {
+ return s.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+
+/**
+ * Build the write plans for a forked theme.
+ * @param {import('../../foundation/discovery/theme-discovery.mjs').DiscoveredTheme} base
+ * @param {ReturnType<typeof themeIdentity>} identity new theme identity
+ * @param {string} themeDir absolute target directory
+ * @returns {import('./add-helpers.mjs').WritePlan[]}
+ */
+function forkThemePlans(base, identity, themeDir) {
+ const baseIdentity = themeIdentity(base.slug);
+ /** @type {import('./add-helpers.mjs').WritePlan[]} */
+ const plans = [];
+
+ // Copy every file the base theme ships (entry first, then the rest), except
+ // the descriptor — we write a fresh one.
+ const filesToCopy = base.files.filter(
+ file => path.posix.basename(file) !== `${baseIdentity.exportName}.doc.mjs`,
+ );
+
+ for (const file of filesToCopy) {
+ const srcPath = path.join(base.sourceDir, file);
+ const newFileName = renameThemeFile(
+ file,
+ baseIdentity.identifier,
+ identity.identifier,
+ );
+ const destPath = assertWithin(newFileName, themeDir, {
+ label: `forked theme file "${newFileName}"`,
+ });
+
+ // Read source bytes; for text, strip copyright and rewrite identifiers.
+ const bytes = fs.readFileSync(srcPath);
+ const text = bytes.toString('utf-8');
+ const isText = Buffer.from(text, 'utf-8').equals(bytes);
+
+ /** @type {string | Buffer} */
+ let contents;
+ if (isText) {
+ contents = rewriteThemeSource(
+ stripCopyrightHeader(text),
+ base.slug,
+ baseIdentity.identifier,
+ identity.slug,
+ identity.identifier,
+ );
+ } else {
+ contents = bytes;
+ }
+ plans.push({path: destPath, contents, createOnly: true});
+ }
+
+ // Write a fresh descriptor — the fork is a new theme, not a derivative.
+ const descriptorPath = assertWithin(identity.descriptor, themeDir, {
+ label: 'theme descriptor file',
+ });
+ plans.push({
+ path: descriptorPath,
+ contents: themeDescriptor(identity),
+ createOnly: true,
+ });
+
+ return plans;
+}
+
/**
* Read bytes back through the same discovery seam Project uses. A write is not
* successful until the requested slug resolves.
@@ -130,7 +314,7 @@ async function verifyThemeContribution(packageDir, manifestFile, owner, slug) {
* @returns {Promise<import('./integration-authoring.type.mjs').IntegrationAddResponse>}
*/
export async function integrationAddTheme(name, options = {}) {
- const {cwd = process.cwd(), dryRun = false} = options;
+ const {cwd = process.cwd(), dryRun = false, from} = options;
const packageDir = findPackageDir(cwd);
const packageFile = path.join(packageDir, 'package.json');
let pkg;
@@ -212,32 +396,64 @@ export async function integrationAddTheme(name, options = {}) {
const themeDir = assertWithin(identity.slug, root, {
label: 'theme directory',
});
- const sourceFile = assertWithin(identity.entry, themeDir, {
- label: 'theme source file',
- });
- const descriptorFile = assertWithin(identity.descriptor, themeDir, {
- label: 'theme descriptor file',
- });
- // An existing folder is filled; only a file this would write is refused.
- for (const file of [sourceFile, descriptorFile]) {
- if (fs.existsSync(file)) {
+
+ // Resolve the base theme when --from is given, before writing anything.
+ /** @type {import('../../foundation/discovery/theme-discovery.mjs').DiscoveredTheme | undefined} */
+ let baseTheme;
+ if (from != null) {
+ if (from === name) {
throw new AstryxError(
- `Refusing to overwrite existing file ${projectPath(path.relative(packageDir, file))}.`,
+ `Cannot fork theme "${from}" into itself.`,
undefined,
- ERROR_CODES.ERR_FILE_EXISTS,
+ ERROR_CODES.ERR_INVALID_ARGUMENT,
);
}
+ baseTheme = resolveBaseTheme(from, packageDir, owner, root);
}
/** @type {import('./add-helpers.mjs').WritePlan[]} */
- const plans = [
- {path: sourceFile, contents: themeSource(identity), createOnly: true},
- {
- path: descriptorFile,
- contents: themeDescriptor(identity),
- createOnly: true,
- },
- ];
+ let plans;
+
+ if (baseTheme) {
+ // Fork: copy the base theme's files, renamed and rewritten.
+ plans = forkThemePlans(baseTheme, identity, themeDir);
+ // Check that no target file already exists.
+ for (const plan of plans) {
+ if (fs.existsSync(plan.path)) {
+ throw new AstryxError(
+ `Refusing to overwrite existing file ${projectPath(path.relative(packageDir, plan.path))}.`,
+ undefined,
+ ERROR_CODES.ERR_FILE_EXISTS,
+ );
+ }
+ }
+ } else {
+ // Blank scaffold.
+ const sourceFile = assertWithin(identity.entry, themeDir, {
+ label: 'theme source file',
+ });
+ const descriptorFile = assertWithin(identity.descriptor, themeDir, {
+ label: 'theme descriptor file',
+ });
+ for (const file of [sourceFile, descriptorFile]) {
+ if (fs.existsSync(file)) {
+ throw new AstryxError(
+ `Refusing to overwrite existing file ${projectPath(path.relative(packageDir, file))}.`,
+ undefined,
+ ERROR_CODES.ERR_FILE_EXISTS,
+ );
+ }
+ }
+ plans = [
+ {path: sourceFile, contents: themeSource(identity), createOnly: true},
+ {
+ path: descriptorFile,
+ contents: themeDescriptor(identity),
+ createOnly: true,
+ },
+ ];
+ }
+
let packageUpdate = packageJsonUpdate(
packageFile,
rootPath,
@@ -309,7 +525,8 @@ export async function integrationAddTheme(name, options = {}) {
writtenFiles.push(manifestPath);
}
- return {
+ /** @type {import('./integration-authoring.type.mjs').IntegrationAddResponse} */
+ const response = {
type: 'integration.add',
data: {
kind: 'theme',
@@ -321,4 +538,8 @@ export async function integrationAddTheme(name, options = {}) {
dryRun,
},
};
+ if (from != null) {
+ response.data.from = from;
+ }
+ return response;
}
diff --git a/packages/cli/api/integration/add-theme.test.mjs b/packages/cli/api/integration/add-theme.test.mjs
index d64444bb5b..a8c8d30e56 100644
--- a/packages/cli/api/integration/add-theme.test.mjs
+++ b/packages/cli/api/integration/add-theme.test.mjs
@@ -310,3 +310,216 @@ describe('integrationAddTheme', () => {
);
});
});
+
+describe('integrationAddTheme --from', () => {
+ it('forks a bundled theme into the integration package', async () => {
+ setup();
+ const result = await integrationAddTheme('ocean', {
+ cwd: tmpDir,
+ from: 'neutral',
+ });
+
+ expect(result.type).toBe('integration.add');
+ expect(result.data.kind).toBe('theme');
+ expect(result.data.name).toBe('ocean');
+ expect(result.data.from).toBe('neutral');
+ expect(result.data.written).toBe(true);
+ expect(result.data.dryRun).toBe(false);
+ expect(result.data.root).toEqual({path: './themes', created: true});
+
+ // The entry file must exist with the new export name.
+ const entry = fs.readFileSync(
+ path.join(tmpDir, 'themes/ocean/oceanTheme.ts'),
+ 'utf-8',
+ );
+ expect(entry).toContain('oceanTheme');
+ expect(entry).toContain("name: 'ocean'");
+ // It must NOT contain the original theme identifier as a prefix.
+ expect(entry).not.toMatch(/\bneutralTheme\b/);
+ expect(entry).not.toMatch(/\bneutralPalettes\b/);
+ expect(entry).not.toMatch(/\bneutralSyntax\b/);
+ expect(entry).toContain('defineTheme');
+
+ // A fresh descriptor, not copied from the base.
+ const descriptor = fs.readFileSync(
+ path.join(tmpDir, 'themes/ocean/oceanTheme.doc.mjs'),
+ 'utf-8',
+ );
+ expect(descriptor).toContain("name: 'ocean'");
+ expect(descriptor).toContain("@astryxdesign/cli/authoring').ThemeDoc");
+ expect(descriptor).toContain('maintained: true');
+
+ // The theme must validate.
+ expect((await validateLocalIntegration(tmpDir)).issues).toEqual([]);
+ });
+
+ it('renames palette and support files from the base theme', async () => {
+ setup();
+ await integrationAddTheme('ocean', {cwd: tmpDir, from: 'neutral'});
+
+ const themeDir = path.join(tmpDir, 'themes/ocean');
+ const files = fs.readdirSync(themeDir).sort();
+ // neutralPalettes.ts → oceanPalettes.ts, etc.
+ expect(files).toContain('oceanTheme.ts');
+ expect(files).toContain('oceanTheme.doc.mjs');
+ expect(files).toContain('oceanPalettes.ts');
+ expect(files).toContain('oceanPaletteRefs.generated.ts');
+ expect(files).toContain('icons.tsx');
+ // Must not contain any file starting with 'neutral'.
+ expect(files.filter(f => f.startsWith('neutral'))).toEqual([]);
+ });
+
+ it('rewrites import paths inside forked files', async () => {
+ setup();
+ await integrationAddTheme('ocean', {cwd: tmpDir, from: 'neutral'});
+
+ const entry = fs.readFileSync(
+ path.join(tmpDir, 'themes/ocean/oceanTheme.ts'),
+ 'utf-8',
+ );
+ // Import references must use the new identifier.
+ expect(entry).toContain('./oceanPaletteRefs.generated');
+ expect(entry).not.toContain('./neutralPaletteRefs.generated');
+ // The icon registry import must also be renamed.
+ expect(entry).toContain('oceanIconRegistry');
+ expect(entry).not.toContain('neutralIconRegistry');
+ });
+
+ it('rewrites CSS custom properties scoped to the base theme', async () => {
+ setup();
+ await integrationAddTheme('ocean', {cwd: tmpDir, from: 'neutral'});
+
+ const entry = fs.readFileSync(
+ path.join(tmpDir, 'themes/ocean/oceanTheme.ts'),
+ 'utf-8',
+ );
+ expect(entry).toContain('--astryx-theme-ocean-');
+ expect(entry).not.toContain('--astryx-theme-neutral-');
+ });
+
+ it('rewrites the syntax theme name', async () => {
+ setup();
+ await integrationAddTheme('ocean', {cwd: tmpDir, from: 'neutral'});
+
+ const entry = fs.readFileSync(
+ path.join(tmpDir, 'themes/ocean/oceanTheme.ts'),
+ 'utf-8',
+ );
+ expect(entry).toContain("'astryx-ocean'");
+ expect(entry).not.toContain("'astryx-neutral'");
+ });
+
+ it('strips the copyright header from forked files', async () => {
+ setup();
+ await integrationAddTheme('ocean', {cwd: tmpDir, from: 'neutral'});
+
+ const entry = fs.readFileSync(
+ path.join(tmpDir, 'themes/ocean/oceanTheme.ts'),
+ 'utf-8',
+ );
+ expect(entry).not.toContain('Copyright (c) Meta Platforms');
+ });
+
+ it('includes data.from in the receipt only when --from is used', async () => {
+ setup();
+ const blank = await integrationAddTheme('plain', {cwd: tmpDir});
+ expect(blank.data).not.toHaveProperty('from');
+
+ const forked = await integrationAddTheme('ocean', {
+ cwd: tmpDir,
+ from: 'neutral',
+ });
+ expect(forked.data.from).toBe('neutral');
+ });
+
+ it('refuses to fork a theme into itself', async () => {
+ setup();
+ await expect(
+ integrationAddTheme('neutral', {cwd: tmpDir, from: 'neutral'}),
+ ).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
+ });
+
+ it('refuses an unknown base theme with a helpful suggestion list', async () => {
+ setup();
+ await expect(
+ integrationAddTheme('ocean', {cwd: tmpDir, from: 'nonexistent'}),
+ ).rejects.toMatchObject({
+ code: 'ERR_UNKNOWN_THEME',
+ message: expect.stringContaining('nonexistent'),
+ });
+ });
+
+ it('dry-runs with --from without writing anything', async () => {
+ setup();
+ const result = await integrationAddTheme('ocean', {
+ cwd: tmpDir,
+ from: 'neutral',
+ dryRun: true,
+ });
+
+ expect(result.data.written).toBe(false);
+ expect(result.data.dryRun).toBe(true);
+ expect(result.data.from).toBe('neutral');
+ expect(result.data.files).toContain('themes/ocean/oceanTheme.ts');
+ expect(result.data.files).toContain('themes/ocean/oceanTheme.doc.mjs');
+ expect(fs.existsSync(path.join(tmpDir, 'themes'))).toBe(false);
+ });
+
+ it('refuses to overwrite when the target already exists', async () => {
+ setup();
+ await integrationAddTheme('ocean', {cwd: tmpDir, from: 'neutral'});
+ await expect(
+ integrationAddTheme('ocean', {cwd: tmpDir, from: 'neutral'}),
+ ).rejects.toMatchObject({code: 'ERR_FILE_EXISTS'});
+ });
+
+ it('works with different bundled themes', async () => {
+ setup();
+ const result = await integrationAddTheme('dusk', {
+ cwd: tmpDir,
+ from: 'gothic',
+ });
+
+ expect(result.data.from).toBe('gothic');
+ const entry = fs.readFileSync(
+ path.join(tmpDir, 'themes/dusk/duskTheme.ts'),
+ 'utf-8',
+ );
+ expect(entry).toContain('duskTheme');
+ expect(entry).toContain("name: 'dusk'");
+ expect(entry).not.toMatch(/\bgothicTheme\b/);
+ expect((await validateLocalIntegration(tmpDir)).issues).toEqual([]);
+ });
+
+ it('forks from a theme the package already owns', async () => {
+ setup();
+ // First, add a blank theme.
+ await integrationAddTheme('base', {cwd: tmpDir});
+ // Then fork it.
+ const result = await integrationAddTheme('variant', {
+ cwd: tmpDir,
+ from: 'base',
+ });
+
+ expect(result.data.from).toBe('base');
+ const entry = fs.readFileSync(
+ path.join(tmpDir, 'themes/variant/variantTheme.ts'),
+ 'utf-8',
+ );
+ expect(entry).toContain('variantTheme');
+ expect(entry).toContain("name: 'variant'");
+ expect((await validateLocalIntegration(tmpDir)).issues).toEqual([]);
+ });
+
+ it('declares the optional CLI peer that reads typed theme descriptors', async () => {
+ setup({includeFiles: false});
+ await integrationAddTheme('ocean', {cwd: tmpDir, from: 'neutral'});
+ const pkg = JSON.parse(
+ fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8'),
+ );
+ expect(pkg.peerDependencies).toEqual({'@astryxdesign/cli': '>=0.6.4'});
+ expect(pkg.peerDependenciesMeta).toEqual({
+ '@astryxdesign/cli': {optional: true},
+ });
+ });
+});
diff --git a/packages/cli/api/integration/integration-authoring.type.mjs b/packages/cli/api/integration/integration-authoring.type.mjs
index 9f9740c308..ae1e455068 100644
--- a/packages/cli/api/integration/integration-authoring.type.mjs
+++ b/packages/cli/api/integration/integration-authoring.type.mjs
@@ -37,7 +37,11 @@
*/
/** @typedef {IntegrationAddBaseOptions} IntegrationAddAgentDocOptions */
-/** @typedef {IntegrationAddBaseOptions} IntegrationAddThemeOptions */
+/**
+ * @typedef {IntegrationAddBaseOptions & {
+ * from?: string,
+ * }} IntegrationAddThemeOptions
+ */
/**
* Options for the generic `integrationAdd` dispatcher. Prefer a per-kind API
@@ -73,6 +77,7 @@
* @property {string[]} files
* @property {boolean} written
* @property {boolean} dryRun
+ * @property {string} [from]
*/
export {};
diff --git a/packages/cli/api/integration/integrationAdd.doc.mjs b/packages/cli/api/integration/integrationAdd.doc.mjs
index f3a67c1496..0b6990a63c 100644
--- a/packages/cli/api/integration/integrationAdd.doc.mjs
+++ b/packages/cli/api/integration/integrationAdd.doc.mjs
@@ -78,6 +78,12 @@ export const doc = {
type: 'string',
description: 'Exact target semver (e.g. 1.2.0). Required for codemod and only valid there.',
},
+ {
+ name: 'options.from',
+ type: 'string',
+ description:
+ 'Slug of an existing theme to fork as the starting point. Only valid for theme.',
+ },
],
returns: [
{
diff --git a/packages/cli/api/integration/integrationAddTheme.doc.mjs b/packages/cli/api/integration/integrationAddTheme.doc.mjs
index 552c143f17..83eb6a005a 100644
--- a/packages/cli/api/integration/integrationAddTheme.doc.mjs
+++ b/packages/cli/api/integration/integrationAddTheme.doc.mjs
@@ -33,6 +33,12 @@ export const doc = {
'Validate and return the same receipt without writing; data.written is false and data.dryRun is true.',
default: 'false',
},
+ {
+ name: 'options.from',
+ type: 'string',
+ description:
+ 'Slug of an existing theme to fork as the starting point. The new theme copies the base and has no link back.',
+ },
],
returns: [
{
@@ -76,6 +82,10 @@ export const doc = {
label: 'Add a theme',
code: "await integrationAddTheme('ocean');",
},
+ {
+ label: 'Fork an existing theme',
+ code: "await integrationAddTheme('ocean', {from: 'neutral'});",
+ },
{
label: 'Preview writes',
code: "await integrationAddTheme('ocean', {dryRun: true});",
diff --git a/packages/cli/clients/cli/commands/integration-add.doc.mjs b/packages/cli/clients/cli/commands/integration-add.doc.mjs
index 25d1ae9acf..6838909a0b 100644
--- a/packages/cli/clients/cli/commands/integration-add.doc.mjs
+++ b/packages/cli/clients/cli/commands/integration-add.doc.mjs
@@ -56,6 +56,12 @@ export const doc = {
description:
"Namespace of this package to place the doc in, as a guide in its `guides` slot; writes the namespace doc when it is missing, and declares the CLI that reads it as an optional `@astryxdesign/cli` peer. Only valid for doc, and not with --replaces or --extends",
},
+ {
+ flag: '--from <theme>',
+ param: 'options.from',
+ description:
+ 'Existing theme slug to fork as a starting point instead of a blank scaffold; the new theme copies the base and has no link back. Only valid for theme',
+ },
{
flag: '--to <version>',
param: 'options.to',
@@ -102,6 +108,10 @@ export const doc = {
cli: "astryx integration add agent-doc 'Run acme verify before finishing.'",
},
{label: 'Add a source theme', cli: 'astryx integration add theme ocean'},
+ {
+ label: 'Fork an existing theme',
+ cli: 'astryx integration add theme ocean --from neutral',
+ },
],
exitCodes: [
{code: 0, when: 'the contribution is written or the dry run succeeds'},
diff --git a/packages/cli/clients/cli/commands/integration.mjs b/packages/cli/clients/cli/commands/integration.mjs
index 0f5a8de5ac..355dbcc2fc 100644
--- a/packages/cli/clients/cli/commands/integration.mjs
+++ b/packages/cli/clients/cli/commands/integration.mjs
@@ -115,6 +115,7 @@ export function registerIntegration(program) {
extends: options.extends,
parent: options.parent,
to: options.to,
+ from: options.from,
});
} catch (error) {
const err =
diff --git a/packages/cli/test/docs-graph.test.mjs b/packages/cli/test/docs-graph.test.mjs
index 5551ea8981..172dd7e593 100644
--- a/packages/cli/test/docs-graph.test.mjs
+++ b/packages/cli/test/docs-graph.test.mjs
@@ -285,10 +285,6 @@ const WRONG_ON_PURPOSE = new Map([
* cannot outlive the decision.
*/
const AWAITING_DECISION = new Map([
- [
- 'astryx integration add theme ocean --from neutral',
- 'the add-a-theme guide shows a fork option the CLI does not have: build it, or drop the paragraph',
- ],
]);
/** The CLI's own reads whose hint lines show commands. */