@astryxdesign/cli 0.1.2-canary.4d9726d → 0.1.2-canary.4eb9849

package/docs/layout.doc.mjs

@@ -1,160 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('../../core/src/docs-types').ReferenceDoc} */
-
-export const docs = {
-  name: 'layout',
-  title: 'Layout',
-  category: 'guide',
-  description:
-    'Frame-first app layout: choosing a shell, budgeting regions, and when to use cards vs rows.',
-
-  sections: [
-    {
-      title: 'Frame First',
-      content: [
-        {
-          type: 'prose',
-          text: 'Decide the frame before writing any content. Real applications are built top-down: pick the shell, name its regions, give each region an explicit size budget, then fill regions with content. Content-first layout (writing sections and wrapping each one in a Card) produces a padded scroll column that reads as a prototype, not a product.',
-        },
-        {
-          type: 'list',
-          style: 'ordered',
-          items: [
-            'Pick the frame: AppShell (top nav and/or side nav apps), Layout + LayoutPanel + LayoutContent (multi-pane tools like explorers and consoles), or a plain content column (documents, marketing, forms)',
-            'Budget regions in px before filling them: side nav 240–280, icon rail 64–72, detail/inspector panel 340–420, filter/facet rail 220–260',
-            'Decide the container policy per region: dense data renders as rows; widget dashboards and galleries render as card grids (see Cards vs Rows)',
-            'Write the responsive contract up front: which regions collapse, overlay, or drop at which breakpoints (see Responsive Contract)',
-          ],
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'A three-region tool frame',
-          code: `// Frame: nav 256 | content flex | inspector 380 (resizable)
-<AppShell sideNav={<SideNav>{/* nav items */}</SideNav>} contentPadding={0}>
-  <Layout>
-    <LayoutContent>{/* dense list or table, edge-to-edge */}</LayoutContent>
-    <LayoutPanel width={380} resizable={{minSizePx: 320, maxSizePx: 480}} hasDivider>
-      {/* inspector for the selected row */}
-    </LayoutPanel>
-  </Layout>
-</AppShell>`,
-        },
-      ],
-    },
-    {
-      title: 'App Archetypes',
-      content: [
-        {
-          type: 'prose',
-          text: 'Match the frame and container policy to the kind of app you are building. These recipes are distilled from product-scale apps built with the design system; container choice tracks the archetype, not personal preference.',
-        },
-        {
-          type: 'table',
-          headers: ['Archetype', 'Frame', 'Container policy'],
-          rows: [
-            [
-              'Tracker / work tool (issues, tickets, CRM)',
-              'AppShell + SideNav; inspector LayoutPanel on select',
-              'Rows only. Grouped edge-to-edge lists, zero cards',
-            ],
-            [
-              'Console / observability (metrics, logs, deploys)',
-              'AppShell + SideNav or TopNav + TabList',
-              'Card grid for dashboard widgets; Table for everything else',
-            ],
-            [
-              'Messaging / feed',
-              'Column frame: rail + sidebar + stream + panel',
-              'Rows and bubbles. No cards in the stream',
-            ],
-            [
-              'Media library / gallery',
-              'AppShell + TopNav; grid content',
-              'Card grid (ClickableCard) with dense metadata rows in detail views',
-            ],
-            [
-              'Settings / forms',
-              'AppShell + SideNav or settings template',
-              'Sections with FormLayout; Card only to group dangerous or billing actions',
-            ],
-          ],
-        },
-        {
-          type: 'prose',
-          text: 'Start from a template that matches the archetype (`npx astryx template --list`), then study its structure with `--skeleton` before customizing.',
-        },
-      ],
-    },
-    {
-      title: 'Cards vs Rows',
-      content: [
-        {
-          type: 'prose',
-          text: 'Card is a widget container, not a list-item wrapper. The fastest way to make an app look like a generic AI prototype is to wrap every record in a Card with a Badge. Dense data — anything the user scans, filters, or selects — belongs in rows: Table for columnar data, List/Item for single-line records, edge-to-edge with dividers and 32–40px row height.',
-        },
-        {
-          type: 'list',
-          style: 'do',
-          items: [
-            'Table (with selection/sorting plugins) for columnar records: hosts, deployments, monitors, users',
-            'List/Item rows for scannable single-line records: issues, files, conversations',
-            'Card for self-contained widgets: KPI tiles, chart panels, gallery entries, settings groups',
-            'EmptyState inside the region when a filter matches nothing',
-          ],
-        },
-        {
-          type: 'list',
-          style: 'dont',
-          items: [
-            'Wrapping each list item in a Card (card soup)',
-            'Stacking full-width Cards as a substitute for page structure',
-            'Nesting Cards inside Cards',
-            'Using Badge as decoration — reserve it for counts and enumerated states; use StatusDot or Token for status and metadata',
-          ],
-        },
-      ],
-    },
-    {
-      title: 'Panels and Inspectors',
-      content: [
-        {
-          type: 'prose',
-          text: 'Master-detail is the backbone of tool UIs: selecting a row opens a fixed-width inspector panel rather than navigating away. Use LayoutPanel in the end slot with an explicit width budget; add resizable (useResizable) for user control, and let the panel overlay the content region below ~1024px instead of compressing it.',
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Inspector that overlays at narrow widths',
-          code: `<LayoutPanel
-  width={380}
-  hasDivider
-  isScrollable
-  label="Details"
-  resizable={{minSizePx: 320, maxSizePx: 480, autoSaveId: 'inspector'}}>
-  {selected ? <DetailFields item={selected} /> : <EmptyState title="Nothing selected" />}
-</LayoutPanel>`,
-        },
-      ],
-    },
-    {
-      title: 'Responsive Contract',
-      content: [
-        {
-          type: 'prose',
-          text: 'Declare breakpoint behavior as a contract before building, and keep it in a comment at the frame root. A typical contract: full frame above 1024px; inspector panels overlay the content column at 1024px and below; the side nav collapses into MobileNav at 768px and below. Deciding this up front keeps every region change intentional instead of emergent.',
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Contract comment at the frame root',
-          code: `// Responsive contract:
-//   > 1024px  nav 256 | content | inspector 380
-//   <= 1024px inspector overlays content (position: absolute, end-aligned)
-//   <= 768px  nav collapses into MobileNav drawer; toolbar actions wrap`,
-        },
-      ],
-    },
-  ],
-};

package/src/api/blog.mjs

@@ -1,192 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Programmatic API for the blog command.
- *
- * The blog is read the same way any feed reader reads it: over the published
- * RSS feed. Listing parses the feed; reading a post fetches the plaintext
- * (.txt) alternate the feed advertises for each item. Nothing here touches the
- * blog's source files — the CLI is just a consumer of the public feed, so the
- * blog's structure can change freely without touching the CLI.
- */
-
-import {AstryxError} from './error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
-import {SITE_URL, SITE_ORIGIN} from '../lib/site.mjs';
-
-/** Abort a feed/post fetch that hangs, and cap how much we'll read. */
-const FETCH_TIMEOUT_MS = 15000;
-const MAX_BYTES = 5 * 1024 * 1024; // 5 MB — a blog feed is never larger.
-
-const FEED_URL = new URL('/rss.xml', SITE_URL).toString();
-
-async function fetchText(url) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
-  let res;
-  try {
-    res = await fetch(url, {
-      signal: controller.signal,
-      redirect: 'follow',
-    });
-  } catch (e) {
-    clearTimeout(timer);
-    const reason = e.name === 'AbortError' ? 'timed out' : e.message;
-    throw new AstryxError(
-      `Could not reach ${url}: ${reason}`,
-      [],
-      ERROR_CODES.ERR_FETCH_FAILED,
-    );
-  }
-  clearTimeout(timer);
-  if (!res.ok) {
-    throw new AstryxError(
-      `Request to ${url} failed with ${res.status}`,
-      [],
-      ERROR_CODES.ERR_FETCH_FAILED,
-    );
-  }
-  const body = await res.text();
-  if (body.length > MAX_BYTES) {
-    throw new AstryxError(
-      `Response from ${url} exceeded ${MAX_BYTES} bytes`,
-      [],
-      ERROR_CODES.ERR_FETCH_FAILED,
-    );
-  }
-  return body;
-}
-
-/**
- * Defense in depth: a post's plaintext URL comes from feed content. Require it
- * to live on the canonical origin so even a tampered feed can't redirect the
- * CLI to another host.
- */
-function assertCanonicalOrigin(target) {
-  let targetOrigin;
-  try {
-    targetOrigin = new URL(target).origin;
-  } catch {
-    throw new AstryxError(
-      `Post has an invalid plaintext URL: "${target}"`,
-      [],
-      ERROR_CODES.ERR_FETCH_FAILED,
-    );
-  }
-  if (targetOrigin !== SITE_ORIGIN) {
-    throw new AstryxError(
-      `Refusing to fetch post text from a non-canonical origin (${targetOrigin})`,
-      [],
-      ERROR_CODES.ERR_FETCH_FAILED,
-    );
-  }
-}
-
-function unescapeXml(value) {
-  return value
-    .replace(/&lt;/g, '<')
-    .replace(/&gt;/g, '>')
-    .replace(/&quot;/g, '"')
-    .replace(/&apos;/g, "'")
-    .replace(/&amp;/g, '&');
-}
-
-function tag(item, name) {
-  const m = item.match(new RegExp(`<${name}[^>]*>([\\s\\S]*?)</${name}>`));
-  return m ? unescapeXml(m[1].trim()) : '';
-}
-
-function tagAll(item, name) {
-  const out = [];
-  const re = new RegExp(`<${name}[^>]*>([\\s\\S]*?)</${name}>`, 'g');
-  let m;
-  while ((m = re.exec(item))) out.push(unescapeXml(m[1].trim()));
-  return out;
-}
-
-/** Extract the plaintext alternate href from an <item>. */
-function textHref(item) {
-  // Match the atom:link alternate regardless of attribute order/quoting; then
-  // confirm it's the text/plain alternate before trusting the href.
-  const re = /<atom:link\b[^>]*?\/?>/g;
-  let m;
-  while ((m = re.exec(item))) {
-    const el = m[0];
-    if (/rel\s*=\s*["']alternate["']/.test(el) &&
-        /type\s*=\s*["']text\/plain["']/.test(el)) {
-      const href = el.match(/href\s*=\s*["']([^"']+)["']/);
-      if (href) return unescapeXml(href[1]);
-    }
-  }
-  return null;
-}
-
-/** Derive a slug from a post link (last path segment). */
-function slugFromLink(link) {
-  try {
-    const path = new URL(link).pathname.replace(/\/$/, '');
-    return path.slice(path.lastIndexOf('/') + 1);
-  } catch {
-    return link;
-  }
-}
-
-function parseFeed(xml) {
-  const items = [];
-  const re = /<item>([\s\S]*?)<\/item>/g;
-  let m;
-  while ((m = re.exec(xml))) {
-    const raw = m[1];
-    const link = tag(raw, 'link');
-    items.push({
-      slug: slugFromLink(link),
-      title: tag(raw, 'title'),
-      description: tag(raw, 'description'),
-      date: tag(raw, 'pubDate'),
-      type: tag(raw, 'category'),
-      authors: tagAll(raw, 'author'),
-      link,
-      textUrl: textHref(raw),
-    });
-  }
-  return items;
-}
-
-/**
- * List posts (from the feed), or read one post (via its .txt alternate).
- * Both envelopes carry `feedUrl` so a caller can hit the RSS feed directly.
- * The feed is always the canonical site — there is no user-supplied URL.
- *
- * @param {string} [slug]
- * @returns {Promise<{type: string, data: unknown}>}
- */
-export async function blog(slug) {
-  const xml = await fetchText(FEED_URL);
-  const posts = parseFeed(xml);
-
-  if (!slug) {
-    return {type: 'blog.list', data: {feedUrl: FEED_URL, posts}};
-  }
-
-  const normalized = slug.toLowerCase();
-  const post = posts.find(p => p.slug.toLowerCase() === normalized);
-  if (!post) {
-    throw new AstryxError(
-      `No blog post with slug "${slug}"`,
-      posts.map(p => ({name: p.slug, reason: 'available post'})),
-      ERROR_CODES.ERR_UNKNOWN_POST,
-    );
-  }
-
-  if (!post.textUrl) {
-    throw new AstryxError(
-      `Post "${slug}" has no plaintext alternate in the feed`,
-      [],
-      ERROR_CODES.ERR_FETCH_FAILED,
-    );
-  }
-
-  assertCanonicalOrigin(post.textUrl);
-  const text = await fetchText(post.textUrl);
-  return {type: 'blog.detail', data: {...post, feedUrl: FEED_URL, text}};
-}

package/src/api/blog.test.mjs

@@ -1,144 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Tests for the blog API — reads the blog over the canonical RSS feed
- * and fetches each post's plaintext (.txt) alternate. `fetch` is stubbed so
- * the tests never hit the network. The feed origin is fixed (not
- * user-configurable), so the tests assert the canonical URLs directly.
- */
-
-import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
-import {blog} from './blog.mjs';
-import {AstryxError} from './error.mjs';
-import {SITE_URL} from '../lib/site.mjs';
-
-const FEED = `<?xml version="1.0" encoding="UTF-8"?>
-<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
-  <channel>
-    <title>Astryx Blog</title>
-    <link>${SITE_URL}/blog</link>
-    <item>
-      <title>How Astryx works</title>
-      <link>${SITE_URL}/blog/how-astryx-works</link>
-      <guid isPermaLink="true">${SITE_URL}/blog/how-astryx-works</guid>
-      <description>Under the hood &amp; more</description>
-      <category>engineering</category>
-      <author>cvkxx</author>
-      <author>cixzhang</author>
-      <pubDate>Mon, 29 Jun 2026 00:00:00 GMT</pubDate>
-      <atom:link rel="alternate" type="text/plain" href="${SITE_URL}/blog/how-astryx-works.txt" />
-    </item>
-    <item>
-      <title>Introducing Astryx</title>
-      <link>${SITE_URL}/blog/introducing-astryx</link>
-      <guid isPermaLink="true">${SITE_URL}/blog/introducing-astryx</guid>
-      <description>The launch</description>
-      <category>update</category>
-      <author>cvkxx</author>
-      <pubDate>Thu, 18 Jun 2026 00:00:00 GMT</pubDate>
-      <atom:link rel="alternate" type="text/plain" href="${SITE_URL}/blog/introducing-astryx.txt" />
-    </item>
-  </channel>
-</rss>`;
-
-const POST_TEXT = '# How Astryx works\n\nThe body of the post.';
-const FEED_URL = `${SITE_URL}/rss.xml`;
-const TXT_URL = `${SITE_URL}/blog/how-astryx-works.txt`;
-
-/** Build a fetch stub from a url→{status,body} map. */
-function stubFetch(routes) {
-  return vi.fn(async (url, opts) => {
-    const u = String(url);
-    const r = routes[u];
-    if (!r) return {ok: false, status: 404, text: async () => 'not found'};
-    if (r.throw) throw r.throw;
-    return {ok: r.status < 400, status: r.status, text: async () => r.body};
-  });
-}
-
-beforeEach(() => {
-  vi.stubGlobal('fetch', stubFetch({
-    [FEED_URL]: {status: 200, body: FEED},
-    [TXT_URL]: {status: 200, body: POST_TEXT},
-    [`${SITE_URL}/blog/introducing-astryx.txt`]: {status: 200, body: 'launch body'},
-  }));
-});
-
-afterEach(() => {
-  vi.unstubAllGlobals();
-});
-
-describe('blog API', () => {
-  it('lists posts parsed from the canonical feed', async () => {
-    const res = await blog();
-    expect(res.type).toBe('blog.list');
-    expect(res.data.feedUrl).toBe(FEED_URL);
-    expect(res.data.posts.map(p => p.slug)).toEqual([
-      'how-astryx-works',
-      'introducing-astryx',
-    ]);
-    expect(res.data.posts[0].authors).toEqual(['cvkxx', 'cixzhang']);
-    expect(res.data.posts[0].textUrl).toBe(TXT_URL);
-    // Entity decoding works (&amp; -> &).
-    expect(res.data.posts[0].description).toBe('Under the hood & more');
-    // The list never fetches post bodies.
-    expect(res.data.posts[0].text).toBeUndefined();
-  });
-
-  it('reads a post via its plaintext alternate', async () => {
-    const res = await blog('how-astryx-works');
-    expect(res.type).toBe('blog.detail');
-    expect(res.data.text).toBe(POST_TEXT);
-    expect(res.data.feedUrl).toBe(FEED_URL);
-    expect(fetch).toHaveBeenCalledWith(TXT_URL, expect.any(Object));
-  });
-
-  it('is case-insensitive on the slug', async () => {
-    const res = await blog('How-Astryx-Works');
-    expect(res.data.slug).toBe('how-astryx-works');
-  });
-
-  it('throws ERR_UNKNOWN_POST with suggestions for a bad slug', async () => {
-    await expect(blog('does-not-exist')).rejects.toMatchObject({
-      code: 'ERR_UNKNOWN_POST',
-    });
-    try {
-      await blog('does-not-exist');
-    } catch (e) {
-      expect(e).toBeInstanceOf(AstryxError);
-      expect(Array.isArray(e.suggestions)).toBe(true);
-      expect(e.suggestions.length).toBeGreaterThan(0);
-    }
-  });
-
-  it('throws ERR_FETCH_FAILED when the feed request fails', async () => {
-    vi.stubGlobal('fetch', stubFetch({
-      [FEED_URL]: {status: 500, body: 'boom'},
-    }));
-    await expect(blog()).rejects.toMatchObject({code: 'ERR_FETCH_FAILED'});
-  });
-
-  it('refuses a post whose plaintext URL is on a different origin (SSRF guard)', async () => {
-    const evilFeed = FEED.replace(
-      `${SITE_URL}/blog/how-astryx-works.txt`,
-      'http://169.254.169.254/latest/meta-data',
-    );
-    vi.stubGlobal('fetch', stubFetch({
-      [FEED_URL]: {status: 200, body: evilFeed},
-      'http://169.254.169.254/latest/meta-data': {status: 200, body: 'SECRETS'},
-    }));
-    await expect(blog('how-astryx-works')).rejects.toMatchObject({
-      code: 'ERR_FETCH_FAILED',
-    });
-    // The internal host must never be fetched.
-    expect(fetch).not.toHaveBeenCalledWith(
-      'http://169.254.169.254/latest/meta-data',
-      expect.anything(),
-    );
-  });
-
-  it('always reads from the canonical feed URL', async () => {
-    await blog();
-    expect(fetch).toHaveBeenCalledWith(FEED_URL, expect.any(Object));
-  });
-});

package/src/commands/blog.mjs

@@ -1,60 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file blog command (hidden) — read the Astryx blog from the published feed.
- *
- * Hidden on purpose: it's not part of the documented command surface and does
- * not appear in --help or the manifest. It reads the blog the same way any
- * feed reader would — over the public RSS feed — and prints a post's plaintext
- * (.txt) variant. Nothing about the blog's structure has to change for this to
- * work; the CLI is just a consumer of the feed.
- *
- *   astryx blog                    List posts from the feed
- *   astryx blog <slug>             Print a post as plaintext
- */
-
-import {getRunPrefix} from '../utils/package-manager.mjs';
-import {humanLog} from '../lib/json.mjs';
-import {cliError} from '../lib/cli-error.mjs';
-import {blog as blogApi} from '../api/blog.mjs';
-
-function formatList({feedUrl, posts}, run) {
-  const lines = [`\nAstryx blog · feed: ${feedUrl}\n`];
-  if (posts.length === 0) {
-    lines.push('No posts found in the feed.');
-    return lines.join('\n');
-  }
-  for (const p of posts) {
-    lines.push(`  ${p.slug}`);
-    lines.push(`    ${p.title}`);
-    if (p.type) lines.push(`    ${p.type}`);
-    if (p.textUrl) lines.push(`    ${p.textUrl}`);
-    lines.push('');
-  }
-  lines.push(`Read one: ${run} astryx blog <slug>`);
-  return lines.join('\n');
-}
-
-export function registerBlog(program) {
-  program
-    .command('blog [slug]', {hidden: true})
-    .description('Read the Astryx blog from the published feed')
-    .action(async slug => {
-      const run = getRunPrefix();
-      let result;
-      try {
-        result = await blogApi(slug);
-      } catch (e) {
-        cliError(e.message, {suggestions: e.suggestions || [], code: e.code});
-        return;
-      }
-
-      if (result.type === 'blog.list') {
-        humanLog(formatList(result.data, run));
-      } else {
-        // blog.detail — print the feed URL, then the plaintext body.
-        humanLog(`Feed: ${result.data.feedUrl}\n`);
-        humanLog(result.data.text);
-      }
-    });
-}