@astryxdesign/cli 0.1.7 → 0.1.8-canary.07362a9

package/{src/api → api/theme}/theme-add.mjs

@@ -8,10 +8,10 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {CLI_ROOT} from '../utils/paths.mjs';
-import {assertWithin, PathSafetyError} from '../utils/path-safety.mjs';
-import {AstryxError} from './error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
+import {CLI_ROOT} from '../../utils/paths.mjs';
+import {assertWithin, PathSafetyError} from '../../utils/path-safety.mjs';
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
 
 const THEMES_DIR = path.join(CLI_ROOT, 'templates', 'themes');
 const MANIFEST_PATH = path.join(THEMES_DIR, 'manifest.json');
@@ -21,19 +21,39 @@ const MANIFEST_PATH = path.join(THEMES_DIR, 'manifest.json');
 const META_COPYRIGHT_HEADER_RE =
   /^(\uFEFF?(?:#![^\r\n]*(?:\r?\n))?)\/\/ Copyright \(c\) Meta Platforms, Inc\. and affiliates\.\r?\n(?:\r?\n)*/;
 
+/**
+ * A single bundled theme entry from `templates/themes/manifest.json`.
+ * @typedef {object} BundledTheme
+ * @property {string} slug
+ * @property {string} displayName
+ * @property {string} description
+ * @property {boolean} maintained
+ * @property {string} entry
+ * @property {string} exportName
+ * @property {string[]} files
+ */
+
+/**
+ * @param {string} source
+ * @returns {string}
+ */
 function stripCopyrightHeader(source) {
   return source.replace(META_COPYRIGHT_HEADER_RE, '$1');
 }
 
-/** Parsed `themes` array from the bundle manifest (empty if not generated). */
+/**
+ * Parsed `themes` array from the bundle manifest (empty if not generated).
+ * @returns {BundledTheme[]}
+ */
 export function listThemes() {
   if (!fs.existsSync(MANIFEST_PATH)) return [];
+  /** @type {{themes?: BundledTheme[]}} */
   let manifest;
   try {
     manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf-8'));
   } catch (err) {
     throw new AstryxError(
-      `Theme bundle manifest is unreadable (${MANIFEST_PATH}): ${err.message}`,
+      `Theme bundle manifest is unreadable (${MANIFEST_PATH}): ${/** @type {any} */ (err).message}`,
       undefined,
       ERROR_CODES.ERR_NO_SOURCE,
     );
@@ -41,12 +61,20 @@ export function listThemes() {
   return Array.isArray(manifest.themes) ? manifest.themes : [];
 }
 
+/**
+ * @param {string} [slug]
+ * @returns {BundledTheme | undefined}
+ */
 function findTheme(slug) {
   if (!slug) return undefined;
   const lc = String(slug).toLowerCase();
   return listThemes().find(t => t.slug.toLowerCase() === lc);
 }
 
+/**
+ * @param {string} slug
+ * @returns {string}
+ */
 function defaultTargetDir(slug) {
   return path.join('src', 'themes', slug);
 }
@@ -160,7 +188,7 @@ export async function themeAdd(slug, options = {}) {
       }
     }
     throw new AstryxError(
-      `Failed to write theme files: ${err.message}`,
+      `Failed to write theme files: ${/** @type {any} */ (err).message}`,
       undefined,
       ERROR_CODES.ERR_WRITE_FAILED,
     );

package/{src → authoring}/codemod.mjs

@@ -65,12 +65,12 @@ export const CodemodEnvelopeSchema = z.discriminatedUnion('type', [
  * Define a file-transforming codemod. Stamp-only: returns the definition with
  * `type: 'code'` injected. Validation happens at the load boundary.
  *
- * @template {import('./types/codemod').AstryxCodemodDef} T
+ * @template {import('../types/codemod').AstryxCodemodDef} T
  * @param {T} def
- * @returns {import('./types/codemod').AstryxCodemod}
+ * @returns {import('../types/codemod').AstryxCodemod}
  */
 export function createCodemod(def) {
-  return /** @type {import('./types/codemod').AstryxCodemod} */ ({
+  return /** @type {import('../types/codemod').AstryxCodemod} */ ({
     ...def,
     type: 'code',
   });
@@ -81,12 +81,12 @@ export function createCodemod(def) {
  * returns the definition with `type: 'config'` injected. Validation happens at
  * the load boundary.
  *
- * @template {import('./types/codemod').AstryxConfigCodemodDef} T
+ * @template {import('../types/codemod').AstryxConfigCodemodDef} T
  * @param {T} def
- * @returns {import('./types/codemod').AstryxConfigCodemod}
+ * @returns {import('../types/codemod').AstryxConfigCodemod}
  */
 export function createConfigCodemod(def) {
-  return /** @type {import('./types/codemod').AstryxConfigCodemod} */ ({
+  return /** @type {import('../types/codemod').AstryxConfigCodemod} */ ({
     ...def,
     type: 'config',
   });

package/{src → authoring}/config.test.mjs

@@ -6,7 +6,7 @@ import {createIntegration} from './integration.mjs';
 import {
   AstryxConfigSchema,
   AstryxIntegrationSchema,
-} from './lib/config-schema.mjs';
+} from '../lib/config-schema.mjs';
 
 // createConfig/createIntegration are now pure typed-identity helpers: they
 // return their argument unchanged and perform NO runtime validation. Validation

package/{src → authoring}/doc.mjs

@@ -24,4 +24,4 @@ export {
   StampedDocSchema,
   LegacyDocSchema,
   ComponentDocSchema,
-} from './schemas/doc-schema.mjs';
+} from '../schemas/doc-schema.mjs';

package/{src → authoring}/doc.test.mjs

@@ -12,7 +12,7 @@ import {
   FunctionDocKindSchema,
   GenericDocKindSchema,
 } from './doc.mjs';
-import {loadComponentDoc} from './lib/component-loader.mjs';
+import {loadComponentDoc} from '../lib/component-loader.mjs';
 
 // The factories are stamp-only (like createConfig / createBlockTemplate): they
 // inject a `type` discriminant and are otherwise identity, performing NO

package/{src → authoring}/template.mjs

@@ -12,4 +12,4 @@
  */
 
 export {createPageTemplate, createBlockTemplate} from '@astryxdesign/core/authoring';
-export {BaseTemplateSchema, TemplateEnvelopeSchema} from './schemas/template-schema.mjs';
+export {BaseTemplateSchema, TemplateEnvelopeSchema} from '../schemas/template-schema.mjs';

package/bin/astryx.mjs

@@ -13,21 +13,22 @@
 // `node-version.mjs` is intentionally dependency-free so it loads on the
 // unsupported runtimes this guard protects against.
 //
-// Sibling `src/` modules are resolved by this bin's REAL path. When the CLI is
-// installed as a package, `npx astryx` runs this file through the
-// `node_modules/.bin/astryx` symlink, and some Node versions resolve relative
-// specifiers from the symlink's directory (→ `node_modules/src/...`) rather
-// than the real package — breaking bare `../src/...` imports with a cryptic
-// ERR_MODULE_NOT_FOUND. realpath-ing `import.meta.url` makes these imports
-// resolve correctly however the bin is invoked (symlink, copy, or Windows
-// shim). Uses only built-ins, so the version gate below still runs first.
+// Sibling package modules (e.g. `cli/`, `lib/`) are resolved by this bin's REAL
+// path. When the CLI is installed as a package, `npx astryx` runs this file
+// through the `node_modules/.bin/astryx` symlink, and some Node versions resolve
+// relative specifiers from the symlink's directory rather than the real package
+// — breaking bare `../…` imports with a cryptic ERR_MODULE_NOT_FOUND.
+// realpath-ing `import.meta.url` makes these imports resolve correctly however
+// the bin is invoked (symlink, copy, or Windows shim). Uses only built-ins, so
+// the version gate below still runs first.
 import {fileURLToPath, pathToFileURL} from 'node:url';
 import {realpathSync} from 'node:fs';
 import {dirname, join} from 'node:path';
 
 const binDir = dirname(realpathSync(fileURLToPath(import.meta.url)));
+/** @param {string} rel */
 const importSrc = rel =>
-  import(pathToFileURL(join(binDir, '..', 'src', rel)).href);
+  import(pathToFileURL(join(binDir, '..', rel)).href);
 
 const {isNodeVersionSupported, unsupportedNodeMessage} =
   await importSrc('lib/node-version.mjs');
@@ -54,7 +55,7 @@ if (!isNodeVersionSupported(process.versions.node)) {
 
 // Imports that transitively load `styleText` must happen AFTER the gate above,
 // so they are dynamically imported here rather than at the top of the module.
-const {program} = await importSrc('index.mjs');
+const {program} = await importSrc('cli/index.mjs');
 const {isJsonMode, toErrorEnvelope} = await importSrc('lib/json.mjs');
 const {handleCommanderError} = await importSrc('lib/json-shim.mjs');
 
@@ -72,6 +73,7 @@ function inJsonMode() {
   return isJsonMode() || process.argv.slice(2).includes('--json');
 }
 
+/** @param {unknown} err */
 function handleFatal(err) {
   // CommanderError (parse errors, --help, unknown command) routes
   // through the JSON shim so that a --json consumer always gets a

package/{src → cli}/commands/blog.mjs

@@ -13,11 +13,44 @@
  *   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';
+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/blog.mjs';
 
+/**
+ * @typedef {object} BlogPost
+ * @property {string} slug
+ * @property {string} title
+ * @property {string} [description]
+ * @property {string} [date]
+ * @property {string} [type]
+ * @property {string[]} [authors]
+ * @property {string} [link]
+ * @property {string | null} [textUrl]
+ */
+
+/**
+ * @typedef {object} BlogListData
+ * @property {string} feedUrl
+ * @property {BlogPost[]} posts
+ */
+
+/**
+ * @typedef {BlogPost & {feedUrl: string, text: string}} BlogDetailData
+ */
+
+/**
+ * @typedef {(
+ *   | {type: 'blog.list', data: BlogListData}
+ *   | {type: 'blog.detail', data: BlogDetailData}
+ * )} BlogResult
+ */
+
+/**
+ * @param {BlogListData} data
+ * @param {string} run
+ */
 function formatList({feedUrl, posts}, run) {
   const lines = [`\nAstryx blog · feed: ${feedUrl}\n`];
   if (posts.length === 0) {
@@ -35,17 +68,25 @@ function formatList({feedUrl, posts}, run) {
   return lines.join('\n');
 }
 
+/**
+ * @param {import('commander').Command} program
+ */
 export function registerBlog(program) {
   program
     .command('blog [slug]', {hidden: true})
     .description('Read the Astryx blog from the published feed')
-    .action(async slug => {
+    .action(async (/** @type {string | undefined} */ slug) => {
       const run = getRunPrefix();
+      /** @type {BlogResult} */
       let result;
       try {
-        result = await blogApi(slug);
+        result = /** @type {BlogResult} */ (await blogApi(slug));
       } catch (e) {
-        cliError(e.message, {suggestions: e.suggestions || [], code: e.code});
+        const err = /** @type {import('../../api/error.mjs').AstryxError} */ (e);
+        cliError(err.message, {
+          suggestions: err.suggestions || [],
+          code: err.code,
+        });
         return;
       }