@astryxdesign/cli 0.6.4 → 0.6.5-canary.00f1ed9

package/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,
@@ -24,6 +30,12 @@ import {
 import {loadManifestObject} from '../../foundation/integrations/integrations.mjs';
 import {themeDescriptorSource} from '../../foundation/integrations/theme-descriptor.mjs';
 import {assertContributionVisible} from '../../foundation/integrations/contribution-inventory.mjs';
+import {
+  THEMES_CLI,
+  themesCliProblem,
+  withCliPeer,
+} from '../../foundation/integrations/cli-requirement.mjs';
+import {stripCopyrightHeader} from '../../foundation/text/copyright-header.mjs';
 import {
   applyWrites,
   findPackageDir,
@@ -65,6 +77,7 @@ function themeIdentity(slug) {
     .join(' ');
   return {
     slug,
+    identifier,
     displayName,
     exportName: `${identifier}Theme`,
     entry: `${identifier}Theme.ts`,
@@ -88,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.
@@ -125,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;
@@ -207,37 +396,86 @@ 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,
-    },
-  ];
-  const packageUpdate = packageJsonUpdate(
+  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,
     path.basename(manifestFile),
   );
+  // A CLI older than the one that reads typed theme descriptors rejects the
+  // themes root and withholds the package's themes and docs. Declare the CLI
+  // that reads them as a peer, so an older one is flagged at install instead.
+  {
+    const expectedOriginal =
+      packageUpdate?.expectedOriginal ?? fs.readFileSync(packageFile);
+    const text = packageUpdate?.contents ?? expectedOriginal.toString('utf-8');
+    const current = JSON.parse(text);
+    if (themesCliProblem(current) != null) {
+      packageUpdate = {
+        contents:
+          JSON.stringify(withCliPeer(current, THEMES_CLI), null, 2) +
+          (text.endsWith('\n') ? '\n' : ''),
+        expectedOriginal,
+      };
+    }
+  }
   if (packageUpdate != null) {
     plans.push({
       path: packageFile,
@@ -287,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',
@@ -299,4 +538,8 @@ export async function integrationAddTheme(name, options = {}) {
       dryRun,
     },
   };
+  if (from != null) {
+    response.data.from = from;
+  }
+  return response;
 }

package/api/integration/add-theme.test.mjs

@@ -77,6 +77,40 @@ describe('integrationAddTheme', () => {
     expect((await validateLocalIntegration(tmpDir)).issues).toEqual([]);
   });
 
+  it('declares the optional CLI peer that reads typed theme descriptors', async () => {
+    setup({includeFiles: false});
+    const result = await integrationAddTheme('ocean', {cwd: tmpDir});
+    expect(result.data.files).toContain('package.json');
+    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},
+    });
+  });
+
+  it('keeps a CLI peer that already reads typed theme descriptors', async () => {
+    const pkg = {
+      name: '@acme/themes',
+      version: '1.0.0',
+      peerDependencies: {'@astryxdesign/cli': '^0.7.2'},
+    };
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify(pkg, null, 2)}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      'export default {};\n',
+    );
+    const result = await integrationAddTheme('ocean', {cwd: tmpDir});
+    expect(result.data.files).not.toContain('package.json');
+    expect(
+      JSON.parse(fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8')),
+    ).toEqual(pkg);
+  });
+
   it('dry-runs the identical receipt without writing anything', async () => {
     setup();
     const beforeManifest = fs.readFileSync(
@@ -276,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},
+    });
+  });
+});