@astryxdesign/cli 0.6.4 → 0.6.5-canary.01972bc

package/api/template/show/show.test.mjs

@@ -0,0 +1,76 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Colocated tests for the template.show leaf — the source it returns is
+ * the source template.copy writes. An agent that prints a template and pastes
+ * it must end up with the same file as one that scaffolds it, demo media
+ * included (spec:AST-028 FR7).
+ */
+
+import {describe, it, expect, beforeAll, afterAll} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {discoverAll, template} from '../template.mjs';
+import {templateCopy} from '../copy/copy.mjs';
+import {templateShow} from './show.mjs';
+
+const SLOW = 60_000;
+/** Astryx's demo-media namespace: only its own previews serve these files. */
+const FIXTURE = '/template-assets/';
+const FIXTURE_IMAGE = /\/template-assets\/[^'"`\s]+\.(png|jpe?g|webp)/i;
+
+const read = (/** @type {string} */ file) => fs.readFileSync(file, 'utf-8');
+
+describe('template.show', () => {
+  /** @type {string} */
+  let dir;
+  /** @type {Awaited<ReturnType<typeof discoverAll>>} */
+  let templates;
+  beforeAll(async () => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'tmpl-show-'));
+    templates = await discoverAll(dir);
+  }, SLOW);
+  afterAll(() => fs.rmSync(dir, {recursive: true, force: true}));
+
+  it('returns exactly the source copy writes, for every template', () => {
+    let withFixtures = 0;
+    templates.forEach((match, index) => {
+      if (read(match.filePath).includes(FIXTURE)) withFixtures += 1;
+      const shown = templateShow(match).data.source;
+      const copied = templateCopy(match, {targetPath: `out-${index}`, cwd: dir});
+      const written = read(
+        path.join(dir, copied.data.outputDir, copied.data.fileName),
+      );
+      expect(shown, match.dirName).toBe(written);
+    });
+    // The templates with demo media are the ones that used to differ.
+    expect(withFixtures).toBeGreaterThan(0);
+  }, SLOW);
+
+  it('reports a replaced count when the source changed, and 0 when it did not', () => {
+    let reported = 0;
+    for (const match of templates) {
+      const raw = read(match.filePath);
+      const {source, demoMediaReplaced} = templateShow(match).data;
+      if (source === raw) expect(demoMediaReplaced, match.dirName).toBe(0);
+      else expect(demoMediaReplaced, match.dirName).toBeGreaterThan(0);
+      reported += demoMediaReplaced;
+    }
+    expect(reported).toBeGreaterThan(0);
+  }, SLOW);
+
+  it('prints a placeholder where a template shows a demo image', async () => {
+    const match = templates.find(
+      t => t.type === 'page' && FIXTURE_IMAGE.test(read(t.filePath)),
+    );
+    expect(match).toBeDefined();
+    if (!match) return;
+    const res = await template(match.dirName, {type: 'page', cwd: dir});
+    expect(res.type).toBe('template.show');
+    if (res.type !== 'template.show') return;
+    expect(res.data.source).not.toContain(FIXTURE);
+    expect(res.data.source).toContain('data:image/svg+xml,');
+    expect(res.data.demoMediaReplaced).toBeGreaterThan(0);
+  }, SLOW);
+});

package/api/template/template-integration.test.mjs

@@ -125,6 +125,20 @@ describe('integration template discovery', () => {
     expect(entry.description).toBe('pricing desc');
   });
 
+  it("reads an integration template's keywords in search and build", async () => {
+    const pkgDir = installWidgets(tmpDir);
+    writeTemplate(pkgDir, 'observatory', {
+      kind: 'page',
+      body: "export default {type: 'page', name: 'Observatory', description: 'Live tiles over a sky view.', category: 'Dashboard - Observatory', keywords: ['telescope', 'star map']};\n",
+    });
+
+    const found = await search('telescope', {cwd: tmpDir, type: 'template'});
+    expect(found.data.results.map(r => r.name)).toContain('observatory');
+    const kit = await build('telescope star map page', {cwd: tmpDir});
+    if (kit.type !== 'build.kit') throw new Error(kit.type);
+    expect(kit.data.start?.name).toBe('observatory');
+  });
+
   it('preserves integration block showcase metadata in list output', async () => {
     const pkgDir = installWidgets(tmpDir);
     writeTemplate(pkgDir, 'chart-showcase', {

package/api/template/template.d.mts

@@ -41,4 +41,4 @@ export function template(name?: string, options?: {
 export type DiscoveredTemplate = import("../../foundation/discovery/template-adapter.mjs").DiscoveredTemplate;
 export type TemplateDiscoveryError = import("../../foundation/discovery/template-adapter.mjs").TemplateDiscoveryError;
 export type TemplateDocModule = import("../../foundation/discovery/template-adapter.mjs").TemplateDocModule;
-export { discoverAll, discoverAll as discoverTemplates, discoverAllWithErrors, discoverCoreTemplates, discoverIntegrationTemplatesForOne, stripTemplateAssetRefs, listTemplates, findRelatedBlocks, findShowcase, extractComponents } from "../../foundation/discovery/template-adapter.mjs";
+export { discoverAll, discoverAll as discoverTemplates, discoverAllWithErrors, discoverCoreTemplates, discoverIntegrationTemplatesForOne, stripTemplateAssetRefs, replaceDemoMedia, listTemplates, findRelatedBlocks, findShowcase, extractComponents } from "../../foundation/discovery/template-adapter.mjs";

package/api/template/template.doc.mjs

@@ -102,6 +102,7 @@ export const doc = {
       type: 'string',
       description:
         'Directory to discover templates and resolve the target path from.',
+      default: 'process.cwd()',
     },
   ],
   returns: [
@@ -113,7 +114,7 @@ export const doc = {
     {
       type: 'template.show',
       description:
-        "The resolved template's raw source plus its description, kind, and the component names it composes.",
+        "The resolved template's source, exactly as a copy writes it, plus its description, kind, the component names it composes, and `demoMediaReplaced` — how many Astryx demo media references (images, posters, videos) in the source were replaced with placeholders for you to swap for your own media.",
     },
     {
       type: 'template.skeleton',
@@ -123,7 +124,7 @@ export const doc = {
     {
       type: 'template.copy',
       description:
-        'A receipt after scaffolding the template into the project: the template id, output directory, written file name, and file count.',
+        'A receipt after scaffolding the template into the project: the template id, output directory, written file name, file count, and `demoMediaReplaced` — how many Astryx demo media references (images, posters, videos) in the written file were replaced with placeholders for you to swap for your own media.',
     },
     {
       type: 'template.cdn',
@@ -134,7 +135,7 @@ export const doc = {
   throws: [
     {
       code: 'ERR_UNKNOWN_TEMPLATE',
-      when: 'the named template does not exist, or --skeleton is run without a name',
+      when: 'the named template does not exist, or options.skeleton is set without a name',
     },
     {
       code: 'ERR_AMBIGUOUS_TEMPLATE',
@@ -152,6 +153,10 @@ export const doc = {
       code: 'ERR_FILE_EXISTS',
       when: 'the copy target already exists and overwrite is not set',
     },
+    {
+      code: 'ERR_WRITE_FAILED',
+      when: 'the copy target could not be written (no permission, read-only mount, full disk); nothing is written',
+    },
   ],
   examples: [
     {label: 'List templates', code: 'const {data} = await template();'},

package/api/template/template.mjs

@@ -41,6 +41,7 @@ export {
   discoverCoreTemplates,
   discoverIntegrationTemplatesForOne,
   stripTemplateAssetRefs,
+  replaceDemoMedia,
   listTemplates,
   findRelatedBlocks,
   findShowcase,

package/api/template/template.type.d.mts

@@ -67,6 +67,7 @@ export type TemplateShowResponse = {
         type: "page" | "block";
         components: string[];
         source: string;
+        demoMediaReplaced: number;
     };
 };
 /**
@@ -91,6 +92,7 @@ export type TemplateCopyResponse = {
         outputDir: string;
         fileName: string;
         filesCopied: number;
+        demoMediaReplaced: number;
     };
 };
 /**

package/api/template/template.type.mjs

@@ -53,6 +53,7 @@
  * @property {'page' | 'block'} data.type
  * @property {string[]} data.components
  * @property {string} data.source
+ * @property {number} data.demoMediaReplaced Astryx demo media references (images, posters, videos) replaced in the returned source: images with a neutral placeholder, videos with an empty source. Swap in your own media at those points; no media is installed. 0 when the template carried none.
  */
 
 /**
@@ -75,6 +76,7 @@
  * @property {string} data.outputDir
  * @property {string} data.fileName
  * @property {number} data.filesCopied
+ * @property {number} data.demoMediaReplaced Astryx demo media references (images, posters, videos) replaced in the written file: images with a neutral placeholder, videos with an empty source. Swap in your own media at those points; no media is installed. 0 when the template carried none.
  */
 
 /**

package/api/theme/add/add.mjs

@@ -15,6 +15,7 @@ import {
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {listAvailableThemes, findTheme} from '../_adapter.mjs';
+import {applyWrites} from '../../integration/add-helpers.mjs';
 // Scaffolded files must not carry our repo boilerplate into a consumer's tree.
 import {stripCopyrightHeader} from '../../../foundation/text/copyright-header.mjs';
 
@@ -136,37 +137,28 @@ export async function themeAdd(slug, options = {}) {
     }
   }
 
-  // Stage to temp files then rename, rolling back partials on failure so a
-  // failed write never leaves a half-written theme. mkdir is inside the try so
-  // a failure (e.g. an ancestor is a file → EEXIST/ENOTDIR) surfaces as a
-  // stable ERR_WRITE_FAILED rather than leaking a raw fs errno + absolute path.
-  const staged = [];
+  // One transaction: every file publishes, or every replaced file gets its
+  // previous bytes back and every created file is removed. mkdir is inside the
+  // try so a failure (e.g. an ancestor is a file → EEXIST/ENOTDIR) surfaces as
+  // a stable ERR_WRITE_FAILED rather than leaking a raw fs errno + absolute path.
   try {
     fs.mkdirSync(resolvedDir, {recursive: true});
-    for (const w of writes) {
+    const plans = writes.map(w => {
+      fs.mkdirSync(path.dirname(w.dest), {recursive: true});
+      // Confine again once the directories exist: one may have been swapped
+      // for a link since the destination was first checked.
       const dest = assertWithin(w.name, resolvedDir, {
         label: `theme destination for ${w.name}`,
       });
-      fs.mkdirSync(path.dirname(dest), {recursive: true});
-      // The staging file is an output path too: confine it, and never write
-      // through an entry that already exists under its name.
-      const tmp = assertWithin(`${w.name}.${process.pid}.tmp`, resolvedDir, {
-        label: `theme staging file for ${w.name}`,
-      });
-      fs.writeFileSync(tmp, scaffoldContents(fs.readFileSync(w.src)), {flag: 'wx'});
-      staged.push({tmp, dest});
-    }
-    for (const s of staged) {
-      fs.renameSync(s.tmp, s.dest);
-    }
+      return {
+        path: dest,
+        contents: scaffoldContents(fs.readFileSync(w.src)),
+        createOnly: !overwrite,
+      };
+    });
+    applyWrites(plans);
   } catch (err) {
-    for (const s of staged) {
-      try {
-        fs.rmSync(s.tmp, {force: true});
-      } catch {
-        /* best-effort */
-      }
-    }
+    if (err instanceof AstryxError) throw err;
     if (err instanceof PathSafetyError) {
       throw new AstryxError(
         err.message,

package/api/theme/add/add.rollback.test.mjs

@@ -0,0 +1,158 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * `theme add` writes a theme as one transaction: when a later file fails to
+ * publish, every file it already replaced gets its previous bytes back and
+ * every file it created is removed. Publishing is forced to fail by wrapping
+ * the two calls that publish a staged file: `linkSync` for a new file and
+ * `renameSync` for a replacement.
+ *
+ * Separate file because vi.mock is hoisted and affects the whole module.
+ */
+
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+const failures = vi.hoisted(() => ({
+  /** Fail the Nth staged-file publish (1-based); 0 disables. */
+  publish: 0,
+  /** Also fail every rollback restore. */
+  restore: false,
+  count: 0,
+}));
+
+vi.mock('node:fs', async importOriginal => {
+  const actual = /** @type {typeof import('node:fs')} */ (
+    await importOriginal()
+  );
+  /** @param {string} source */
+  const isStaged = source => path.basename(String(source)).includes('.tmp');
+  /** @param {string} source */
+  const isRestore = source =>
+    path.basename(String(source)).includes('.restore-');
+  /** @param {string} source @param {string} op */
+  const maybeFail = (source, op) => {
+    if (isStaged(source) && failures.publish > 0) {
+      failures.count++;
+      if (failures.count === failures.publish) {
+        throw Object.assign(new Error(`EIO: forced ${op} failure`), {
+          code: 'EIO',
+        });
+      }
+    }
+    if (isRestore(source) && failures.restore) {
+      throw Object.assign(new Error(`EIO: forced restore failure`), {
+        code: 'EIO',
+      });
+    }
+  };
+  return {
+    ...actual,
+    linkSync: vi.fn((source, destination) => {
+      maybeFail(source, 'link');
+      return actual.linkSync(source, destination);
+    }),
+    renameSync: vi.fn((source, destination) => {
+      maybeFail(source, 'rename');
+      return actual.renameSync(source, destination);
+    }),
+  };
+});
+
+const fs = await import('node:fs');
+const {themeAdd} = await import('./add.mjs');
+const {listThemes} = await import('../_adapter.mjs');
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-themeadd-rollback-'));
+  failures.publish = 0;
+  failures.restore = false;
+  failures.count = 0;
+});
+
+afterEach(() => {
+  failures.publish = 0;
+  failures.restore = false;
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+function stoneFiles() {
+  const theme = listThemes().find(entry => entry.slug === 'stone');
+  if (!theme) throw new Error('missing bundled theme stone');
+  expect(theme.files.length).toBeGreaterThanOrEqual(2);
+  return theme.files.map(name =>
+    path.join(tmpDir, 'src', 'themes', 'stone', name),
+  );
+}
+
+/** Entries staging or rollback left behind in the theme directory. */
+function strays() {
+  const dir = path.join(tmpDir, 'src', 'themes', 'stone');
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, {recursive: true})
+    .map(String)
+    .filter(name => name.includes('.tmp') || name.includes('.restore-'));
+}
+
+describe('themeAdd rolls back a partial write', () => {
+  it('removes every created file when the second publish fails', async () => {
+    const files = stoneFiles();
+    failures.publish = 2;
+
+    await expect(themeAdd('stone', {cwd: tmpDir})).rejects.toMatchObject({
+      code: 'ERR_WRITE_FAILED',
+    });
+
+    for (const file of files) expect(fs.existsSync(file)).toBe(false);
+    expect(strays()).toEqual([]);
+  });
+
+  it('restores every replaced byte when the second publish fails', async () => {
+    const files = stoneFiles();
+    fs.mkdirSync(path.dirname(files[0]), {recursive: true});
+    const before = Buffer.from([0x00, 0xff, 0x0a, 0x62, 0x65, 0x66]);
+    fs.writeFileSync(files[0], before);
+    failures.publish = 2;
+
+    await expect(
+      themeAdd('stone', {cwd: tmpDir, overwrite: true}),
+    ).rejects.toMatchObject({code: 'ERR_WRITE_FAILED'});
+
+    expect(fs.readFileSync(files[0]).equals(before)).toBe(true);
+    for (const file of files.slice(1)) expect(fs.existsSync(file)).toBe(false);
+    expect(strays()).toEqual([]);
+  });
+
+  it('names a file it could not restore', async () => {
+    const files = stoneFiles();
+    fs.mkdirSync(path.dirname(files[0]), {recursive: true});
+    fs.writeFileSync(files[0], 'before\n');
+    failures.publish = 2;
+    failures.restore = true;
+
+    let error;
+    try {
+      await themeAdd('stone', {cwd: tmpDir, overwrite: true});
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error?.code).toBe('ERR_WRITE_FAILED');
+    expect(error?.message).toContain('Could not restore');
+    expect(error?.message).toContain(files[0]);
+  });
+
+  it('writes every file when nothing fails', async () => {
+    const files = stoneFiles();
+
+    const result = await themeAdd('stone', {cwd: tmpDir});
+
+    expect(result.type).toBe('theme.add');
+    for (const file of files) expect(fs.existsSync(file)).toBe(true);
+    expect(strays()).toEqual([]);
+  });
+});

package/api/theme/add/add.staging.test.mjs

@@ -6,14 +6,15 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import {themeAdd} from './add.mjs';
 import {listThemes} from '../_adapter.mjs';
-import {isErrorCode} from '../../../foundation/response/error-codes.mjs';
 
 let tmpDir;
 let outsideDir;
 
 beforeEach(() => {
   tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-themeadd-staging-'));
-  outsideDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-themeadd-outside-'));
+  outsideDir = fs.mkdtempSync(
+    path.join(os.tmpdir(), 'astryx-themeadd-outside-'),
+  );
 });
 
 afterEach(() => {
@@ -22,45 +23,61 @@ afterEach(() => {
 });
 
 /**
- * Put a symlink where `theme add` stages the first file of `slug`.
+ * Where `theme add` writes the first file of `slug`.
  * @param {string} slug
- * @param {string} target
  */
-function plantStagingLink(slug, target) {
+function firstDestination(slug) {
   const theme = listThemes().find(entry => entry.slug === slug);
   if (!theme) throw new Error(`missing bundled theme ${slug}`);
-  const first = theme.files[0];
-  const dest = path.join(tmpDir, 'src', 'themes', slug, first);
+  const dest = path.join(tmpDir, 'src', 'themes', slug, theme.files[0]);
   fs.mkdirSync(path.dirname(dest), {recursive: true});
-  fs.symlinkSync(target, `${dest}.${process.pid}.tmp`);
   return dest;
 }
 
+// Staging names are unpredictable and created exclusively, so an entry planted
+// at a predictable name beside the destination is never written through.
 describe('themeAdd staging writes stay inside the project', () => {
-  it('refuses a staging path that links outside the project', async () => {
+  it('never writes through a link planted at a predictable staging name', async () => {
     const victim = path.join(outsideDir, 'victim.txt');
     fs.writeFileSync(victim, 'outside\n');
-    const dest = plantStagingLink('stone', victim);
+    const dest = firstDestination('stone');
+    fs.symlinkSync(victim, `${dest}.${process.pid}.tmp`);
+
+    await themeAdd('stone', {cwd: tmpDir});
 
-    await expect(themeAdd('stone', {cwd: tmpDir})).rejects.toMatchObject({
-      code: 'ERR_PATH_TRAVERSAL',
-    });
     expect(fs.readFileSync(victim, 'utf-8')).toBe('outside\n');
-    expect(fs.existsSync(dest)).toBe(false);
+    expect(fs.lstatSync(dest).isFile()).toBe(true);
   });
 
-  it('never creates a file through a dangling staging link', async () => {
+  it('never creates a file through a dangling link at a predictable staging name', async () => {
     const victim = path.join(outsideDir, 'created.txt');
-    plantStagingLink('stone', victim);
+    fs.symlinkSync(victim, `${firstDestination('stone')}.${process.pid}.tmp`);
+
+    await themeAdd('stone', {cwd: tmpDir});
+
+    expect(fs.existsSync(victim)).toBe(false);
+  });
+
+  it('refuses to replace a destination that links outside the project', async () => {
+    const victim = path.join(outsideDir, 'victim.txt');
+    fs.writeFileSync(victim, 'outside\n');
+    const dest = firstDestination('stone');
+    fs.symlinkSync(victim, dest);
 
-    let error;
-    try {
-      await themeAdd('stone', {cwd: tmpDir});
-    } catch (caught) {
-      error = caught;
-    }
+    await expect(
+      themeAdd('stone', {cwd: tmpDir, overwrite: true}),
+    ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+    expect(fs.readFileSync(victim, 'utf-8')).toBe('outside\n');
+    expect(fs.lstatSync(dest).isSymbolicLink()).toBe(true);
+  });
 
-    expect(isErrorCode(error?.code)).toBe(true);
+  it('never creates a file through a dangling destination link', async () => {
+    const victim = path.join(outsideDir, 'created.txt');
+    fs.symlinkSync(victim, firstDestination('stone'));
+
+    await expect(themeAdd('stone', {cwd: tmpDir})).rejects.toMatchObject({
+      code: 'ERR_PATH_TRAVERSAL',
+    });
     expect(fs.existsSync(victim)).toBe(false);
   });
 });

package/api/theme/build/build.d.mts

@@ -1,6 +1,16 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
+/**
+ * Why `theme build` has no Core to generate with, and the fix for where it
+ * ran: the Astryx repository builds Core, an app installs it, and an installed
+ * Core that will not load is named.
+ *
+ * @param {string} cwd
+ * @param {any} importError - Why the import failed, when it threw.
+ * @returns {string}
+ */
+export function coreUnavailableMessage(cwd: string, importError: any): string;
 /**
  * Import specifier for install/scaffold instructions. Drops a leading `src/`
  * from the cwd-relative dir (most consumers import from a file under src/) but
@@ -106,3 +116,17 @@ export function themeBuildFamily(files: string[], options: {
  * validateAdaptationEnrollment)
  */
 export type ComponentValueClass = "builtin" | "enrollment" | "unresolved";
+/**
+ * The bindings one Core provides: the namespaces interception spreads, the
+ * functions the build calls, and why the import failed, if it did.
+ */
+export type CoreBindings = {
+    themeModule: any;
+    rootModule: any;
+    importError: any;
+    defineTheme: any;
+    generateThemeRulesSplit: any;
+    generateOnMediaCSS: any;
+    generateAdaptationCSS: any;
+    dataTokenDefaults: any;
+};

package/api/theme/build/build.family.test.mjs

@@ -251,23 +251,18 @@ describe('themeBuildFamily()', () => {
     const dir = makeDir();
     const files = writeFamily(dir);
     const outputDir = path.join(dir, 'themes');
-    const blockedTmp = path.join(
-      outputDir,
-      `${FAMILY_KEY}.js.${process.pid}.tmp`,
-    );
-    fs.mkdirSync(blockedTmp);
+    // A directory where the JS output goes fails its staging after the CSS
+    // output was already staged.
+    fs.mkdirSync(path.join(outputDir, `${FAMILY_KEY}.js`));
 
     await expect(build(dir, files)).rejects.toThrow(
       /Failed to write theme outputs/,
     );
-    for (const output of OUTPUTS) {
-      expect(fs.existsSync(path.join(outputDir, output))).toBe(false);
-    }
+    expect(fs.existsSync(path.join(outputDir, `${FAMILY_KEY}.css`))).toBe(false);
+    expect(fs.existsSync(path.join(outputDir, `${FAMILY_KEY}.d.ts`))).toBe(false);
     expect(
-      fs.existsSync(
-        path.join(outputDir, `${FAMILY_KEY}.css.${process.pid}.tmp`),
-      ),
-    ).toBe(false);
+      fs.readdirSync(outputDir).filter(name => name.includes('.tmp-')),
+    ).toEqual([]);
   });
 
   it('rejects invalid graphs and keys before touching an existing trio', async () => {