@glossarist/concept-browser 0.7.100 → 0.7.102

package/cli/index.mjs

@@ -1,257 +1,20 @@
 #!/usr/bin/env node
-
-/**
- * Glossarist Concept Browser CLI.
- *
- * Commands:
- *   fetch      Fetch/update datasets (from GCR packages or source repos)
- *   generate   Convert harmonized YAML concepts to JSON-LD static files
- *   edges      Build cross-reference edges from generated concept data
- *   build      Full pipeline: fetch + generate + edges + vite build
- *   site       Same as build (alias)
- *   normalize  NFC-normalize YAML files in .datasets/ (use --check for CI gate)
- *   doctor     Diagnose the local environment (deps, datasets, shapes, context)
- *
- * Options:
- *   --site <id>  Site config to use (looks for site-config.yml in CWD)
- *
- * Environment:
- *   SITE_CONFIG          Path to site config file (overrides --site)
- *   SITE_ID              Site config ID (overrides --site)
- *   GITHUB_TOKEN         GitHub token for private repos
- */
-
-import { loadSiteConfig } from '../scripts/load-site-config.mjs';
-import { existsSync } from 'fs';
-import { resolve, dirname } from 'path';
+// Thin ESM shim so `concept-browser` bin works from npm consumers that
+// don't run TypeScript natively. The real logic lives in cli/index.ts.
+// This shim uses tsx to load the .ts entry point at runtime.
+// When TODO.typescript/03 is complete, this shim may be replaced by a
+// compiled cli/index.js output.
 import { fileURLToPath } from 'url';
+import { resolve, dirname } from 'path';
+import { spawnSync } from 'child_process';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const pkgRoot = resolve(__dirname, '..');
-
-const commands = {
-  fetch:    async () => (await import('../scripts/fetch-datasets.mjs')).main(),
-  generate: async () => { await import('../scripts/generate-data.mjs'); },
-  edges:    async () => (await import('../scripts/build-edges.js')).main(),
-  about:    async () => (await import('../scripts/process-about-pages.mjs')).main(),
-};
-
-function parseArgs(argv) {
-  const positional = [];
-  const named = {};
-  for (let i = 0; i < argv.length; i++) {
-    if (argv[i].startsWith('--') && i + 1 < argv.length) {
-      named[argv[i].slice(2)] = argv[i + 1];
-      i++;
-    } else if (!argv[i].startsWith('-')) {
-      positional.push(argv[i]);
-    }
-  }
-  return { positional, named };
-}
-
-async function main() {
-  const args = process.argv.slice(2);
-  const { positional, named } = parseArgs(args);
-  const cmd = positional[0];
-
-  if (!cmd || cmd === 'help' || cmd === '--help') {
-    console.log(`concept-browser <command> [options]
-
-Commands:
-  fetch      Fetch/update datasets from GCR packages or source repos
-  generate   Convert YAML concepts to JSON-LD static data
-  edges      Build cross-reference edges from generated concepts
-  about      Compile per-dataset and per-group about pages
-  build      Full pipeline (fetch + generate + edges + about + vite build)
-  site       Same as build
-  normalize  NFC-normalize YAML files in .datasets/
-  doctor     Diagnose the local environment (deps, datasets, shapes, context)
-
-Options:
-  --site <id>  Site config ID (looks for site-config.yml in CWD)
-  --check      (normalize only) Non-mutating; exit 1 if any file is not NFC
-
-Environment:
-  SITE_CONFIG          Site config file path (highest priority)
-  SITE_ID              Site config ID (same as --site)
-  GITHUB_TOKEN         GitHub token for private repos`);
-    process.exit(cmd ? 0 : 1);
-  }
-
-  // Pre-load site config so scripts can use it
-  if (!process.env.SITE_CONFIG && !process.env.SITE_ID && named.site) {
-    process.env.SITE_ID = named.site;
-  }
-  const { config } = loadSiteConfig(named.site ? [named.site] : []);
-
-  if (cmd === 'build' || cmd === 'site') {
-    if (!process.env.BASE_PATH && config?.basePath) {
-      process.env.BASE_PATH = config.basePath;
-    }
-    for (const step of ['fetch', 'generate', 'edges', 'about']) {
-      console.log(`\n=== ${step.toUpperCase()} ===\n`);
-      await commands[step]();
-    }
-
-    // Generate favicons from site logo
-    const fs = await import('fs');
-    const publicDir = resolve(process.cwd(), 'public');
-    fs.mkdirSync(publicDir, { recursive: true });
-
-    const branding = config?.branding || {};
-    const faviconSrc =
-      (branding.favicon && resolve(process.cwd(), branding.favicon)) ||
-      (branding.logo?.localPath && resolve(process.cwd(), branding.logo.localPath)) ||
-      resolve(pkgRoot, 'public', 'favicon.svg');
-
-    let faviconHtml = '';
-    if (fs.existsSync(faviconSrc)) {
-      console.log(`\n=== FAVICONS ===\n`);
-      const favicons = (await import('favicons')).default;
-      const source = fs.readFileSync(faviconSrc);
-      const response = await favicons(source, {
-        appName: config?.title || 'Glossarist',
-        background: branding.primaryColor || '#2563eb',
-        theme_color: branding.primaryColor || '#2563eb',
-        icons: {
-          android: false,
-          appleIcon: true,
-          appleStartup: false,
-          favicons: true,
-          windows: false,
-          yandex: false,
-        },
-      });
-
-      // Write all generated images and files to public/
-      for (const img of response.images) {
-        fs.writeFileSync(resolve(publicDir, img.name), img.contents);
-      }
-      for (const file of response.files) {
-        fs.writeFileSync(resolve(publicDir, file.name), file.contents);
-      }
-
-      // Keep the original SVG for dark mode support
-      if (faviconSrc.endsWith('.svg')) {
-        fs.copyFileSync(faviconSrc, resolve(publicDir, 'favicon.svg'));
-      }
-
-      faviconHtml = response.html.join('\n    ');
-      // Add SVG favicon
-      if (faviconSrc.endsWith('.svg')) {
-        faviconHtml += '\n    <link rel="icon" type="image/svg+xml" href="/favicon.svg">';
-      }
-      // Write tags for Vite plugin to pick up
-      fs.writeFileSync(resolve(publicDir, 'favicon-links.html'), faviconHtml);
-      console.log(`  Generated ${response.images.length} favicon files`);
-    }
-
-    // Pass favicon tags to Vite via env
-    if (faviconHtml) {
-      const basePath = process.env.BASE_PATH?.replace(/\/+$/, '') || '';
-      if (basePath) {
-        faviconHtml = faviconHtml.replace(/(href|content)="\/([^"]+)"/g, `$1="${basePath}/$2"`);
-      }
-      process.env.FAVICON_HTML = faviconHtml;
-    }
-
-    // Pass branding info for HTML transformation
-    process.env.SITE_TITLE = config?.title || 'Glossarist';
-    if (branding.fonts?.header || branding.fonts?.body) {
-      const fontFamilies = [];
-      if (branding.fonts.header?.source === 'google') {
-        const w = (branding.fonts.header.weights || [400, 700]).join(';');
-        fontFamilies.push(`family=${branding.fonts.header.family.replace(/ /g, '+')}:wght@${w}`);
-      }
-      if (branding.fonts.body?.source === 'google') {
-        const w = (branding.fonts.body.weights || [400, 700]).join(';');
-        fontFamilies.push(`family=${branding.fonts.body.family.replace(/ /g, '+')}:wght@${w}`);
-      }
-      if (fontFamilies.length) {
-        process.env.SITE_FONTS_URL = `https://fonts.googleapis.com/css2?${fontFamilies.join('&')}&display=swap`;
-      }
-    }
-
-    // Bridge data to Astro content collections
-    console.log(`\n=== BRIDGE DATA ===\n`);
-    const bridge = resolve(pkgRoot, 'scripts', 'bridge-to-astro.mjs');
-    if (existsSync(bridge)) {
-      await import(`file://${bridge}`);
-    }
-
-    // Run Astro build (TODO.astro/22)
-    console.log(`\n=== BUILD ASTRO ===\n`);
-    const astroConfig = resolve(pkgRoot, 'astro.config.mjs');
-    if (existsSync(astroConfig)) {
-      try {
-        const { build: astroBuild } = await import('astro');
-        await astroBuild({ root: pkgRoot, logLevel: 'info' });
-      } catch (e) {
-        console.warn(`  Astro build failed (${e.message}), falling back to Vite SPA`);
-        console.log(`\n=== BUILD SPA ===\n`);
-        const viteConfig = resolve(pkgRoot, 'vite.config.ts');
-        const { build: viteBuild } = await import('vite');
-        await viteBuild({ configFile: viteConfig, root: pkgRoot, mode: 'production' });
-      }
-    } else {
-      // Fall back to Vite SPA if Astro config doesn't exist
-      console.log(`\n=== BUILD SPA ===\n`);
-      const viteConfig = resolve(pkgRoot, 'vite.config.ts');
-      const { build: viteBuild } = await import('vite');
-      await viteBuild({ configFile: viteConfig, root: pkgRoot, mode: 'production' });
-    }
-
-    // Run postbuild (404 page) via dynamic import
-    const postbuild = resolve(pkgRoot, 'scripts', 'generate-404.js');
-    if (existsSync(postbuild)) {
-      await import(`file://${postbuild}`);
-    }
-
-    return;
-  }
-
-  const runner = commands[cmd];
-  if (runner) {
-    await runner();
-    return;
-  }
-
-  if (cmd === 'normalize') {
-    const { normalizeYaml } = await import('../scripts/normalize-yaml.mjs');
-    const check = process.argv.includes('--check');
-    const paths = process.argv.slice(2).filter(a => !a.startsWith('-') && a !== 'normalize');
-    const { checked, nonNfc, fixed } = normalizeYaml({ check, paths });
-    if (check) {
-      if (nonNfc === 0) {
-        console.log(`NFC OK: ${checked} file(s) checked, all normalized`);
-        return;
-      }
-      console.error(`NFC check failed: ${nonNfc} of ${checked} file(s) are not NFC-normalized\n`);
-      for (const f of fixed) console.error(`  ${f}`);
-      process.exit(1);
-    }
-    if (nonNfc === 0) {
-      console.log(`NFC OK: ${checked} file(s) checked, all already normalized`);
-    } else {
-      console.log(`Normalized ${nonNfc} of ${checked} file(s)`);
-      for (const f of fixed) console.log(`  ${f}`);
-    }
-    return;
-  }
-
-  if (cmd === 'doctor') {
-    const { main: doctorMain } = await import('../scripts/doctor.mjs');
-    await doctorMain();
-    return;
-  }
+const entry = resolve(__dirname, 'index.ts');
 
-  console.error(`Unknown command: ${cmd}`);
-  console.error('Run `concept-browser help` for usage.');
-  process.exit(1);
-}
+const result = spawnSync(
+  process.execPath,
+  ['--import', 'tsx', entry, ...process.argv.slice(2)],
+  { stdio: 'inherit', cwd: process.cwd() }
+);
 
-main().catch(e => {
-  console.error(e);
-  process.exit(1);
-});
+process.exit(result.status ?? 1);

package/cli/index.ts

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+
+/**
+ * Glossarist Concept Browser CLI.
+ *
+ * Commands:
+ *   fetch      Fetch/update datasets (from GCR packages or source repos)
+ *   generate   Convert harmonized YAML concepts to JSON-LD static files
+ *   edges      Build cross-reference edges from generated concept data
+ *   build      Full pipeline: fetch + generate + edges + vite build
+ *   site       Same as build (alias)
+ *   normalize  NFC-normalize YAML files in .datasets/ (use --check for CI gate)
+ *   doctor     Diagnose the local environment (deps, datasets, shapes, context)
+ *
+ * Options:
+ *   --site <id>  Site config to use (looks for site-config.yml in CWD)
+ *
+ * Environment:
+ *   SITE_CONFIG          Path to site config file (overrides --site)
+ *   SITE_ID              Site config ID (overrides --site)
+ *   GITHUB_TOKEN         GitHub token for private repos
+ */
+
+// Scripts are still .mjs (TODO.typescript/02). These imports will be fully
+// typed once the scripts convert to .ts.
+// @ts-expect-error — .mjs module without declaration
+import { loadSiteConfig } from '../scripts/load-site-config.mjs';
+import { existsSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname: string = dirname(fileURLToPath(import.meta.url));
+const pkgRoot: string = resolve(__dirname, '..');
+
+interface ParsedArgs {
+  positional: string[];
+  named: Record<string, string>;
+}
+
+type CommandRunner = () => Promise<void>;
+
+const commands: Record<string, CommandRunner> = {
+  fetch:    async () => (await import('../scripts/fetch-datasets.mjs' as string)).main(),
+  generate: async () => { await import('../scripts/generate-data.mjs' as string); },
+  edges:    async () => (await import('../scripts/build-edges.js' as string)).main(),
+  about:    async () => (await import('../scripts/process-about-pages.mjs' as string)).main(),
+};
+
+function parseArgs(argv: readonly string[]): ParsedArgs {
+  const positional: string[] = [];
+  const named: Record<string, string> = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--') && i + 1 < argv.length) {
+      named[argv[i].slice(2)] = argv[i + 1];
+      i++;
+    } else if (!argv[i].startsWith('-')) {
+      positional.push(argv[i]);
+    }
+  }
+  return { positional, named };
+}
+
+interface BrandingFonts {
+  source?: string;
+  family?: string;
+  weights?: number[];
+}
+
+interface BrandingConfig {
+  favicon?: string;
+  logo?: { localPath?: string };
+  primaryColor?: string;
+  fonts?: { header?: BrandingFonts; body?: BrandingFonts };
+}
+
+interface SiteConfig {
+  basePath?: string;
+  title?: string;
+  branding?: BrandingConfig;
+}
+
+interface FaviconResponse {
+  images: Array<{ name: string; contents: string | Buffer }>;
+  files: Array<{ name: string; contents: string | Buffer }>;
+  html: string[];
+}
+
+async function runBuildPipeline(config: SiteConfig | null): Promise<void> {
+  if (!process.env.BASE_PATH && config?.basePath) {
+    process.env.BASE_PATH = config.basePath;
+  }
+  for (const step of ['fetch', 'generate', 'edges', 'about'] as const) {
+    console.log(`\n=== ${step.toUpperCase()} ===\n`);
+    await commands[step]();
+  }
+
+  const fs = await import('fs');
+  const publicDir: string = resolve(process.cwd(), 'public');
+  fs.mkdirSync(publicDir, { recursive: true });
+
+  const branding: BrandingConfig = config?.branding ?? {};
+  const faviconSrc: string =
+    (branding.favicon && resolve(process.cwd(), branding.favicon)) ||
+    (branding.logo?.localPath && resolve(process.cwd(), branding.logo.localPath)) ||
+    resolve(pkgRoot, 'public', 'favicon.svg');
+
+  let faviconHtml = '';
+  if (fs.existsSync(faviconSrc)) {
+    console.log(`\n=== FAVICONS ===\n`);
+    const favicons = (await import('favicons')).default;
+    const source: Buffer = fs.readFileSync(faviconSrc);
+    const response: FaviconResponse = await favicons(source, {
+      appName: config?.title || 'Glossarist',
+      background: branding.primaryColor || '#2563eb',
+      theme_color: branding.primaryColor || '#2563eb',
+      icons: {
+        android: false,
+        appleIcon: true,
+        appleStartup: false,
+        favicons: true,
+        windows: false,
+        yandex: false,
+      },
+    });
+
+    for (const img of response.images) {
+      fs.writeFileSync(resolve(publicDir, img.name), img.contents);
+    }
+    for (const file of response.files) {
+      fs.writeFileSync(resolve(publicDir, file.name), file.contents);
+    }
+
+    if (faviconSrc.endsWith('.svg')) {
+      fs.copyFileSync(faviconSrc, resolve(publicDir, 'favicon.svg'));
+    }
+
+    faviconHtml = response.html.join('\n    ');
+    if (faviconSrc.endsWith('.svg')) {
+      faviconHtml += '\n    <link rel="icon" type="image/svg+xml" href="/favicon.svg">';
+    }
+    fs.writeFileSync(resolve(publicDir, 'favicon-links.html'), faviconHtml);
+    console.log(`  Generated ${response.images.length} favicon files`);
+  }
+
+  if (faviconHtml) {
+    const basePath: string = process.env.BASE_PATH?.replace(/\/+$/, '') || '';
+    if (basePath) {
+      faviconHtml = faviconHtml.replace(/(href|content)="\/([^"]+)"/g, `$1="${basePath}/$2"`);
+    }
+    process.env.FAVICON_HTML = faviconHtml;
+  }
+
+  process.env.SITE_TITLE = config?.title || 'Glossarist';
+  if (branding.fonts?.header || branding.fonts?.body) {
+    const fontFamilies: string[] = [];
+    if (branding.fonts.header?.source === 'google') {
+      const w: string = (branding.fonts.header.weights || [400, 700]).join(';');
+      fontFamilies.push(`family=${branding.fonts.header.family!.replace(/ /g, '+')}:wght@${w}`);
+    }
+    if (branding.fonts.body?.source === 'google') {
+      const w: string = (branding.fonts.body.weights || [400, 700]).join(';');
+      fontFamilies.push(`family=${branding.fonts.body.family!.replace(/ /g, '+')}:wght@${w}`);
+    }
+    if (fontFamilies.length) {
+      process.env.SITE_FONTS_URL = `https://fonts.googleapis.com/css2?${fontFamilies.join('&')}&display=swap`;
+    }
+  }
+
+  console.log(`\n=== BRIDGE DATA ===\n`);
+  const bridge: string = resolve(pkgRoot, 'scripts', 'bridge-to-astro.mjs');
+  if (existsSync(bridge)) {
+    await import(`file://${bridge}`);
+  }
+
+  console.log(`\n=== BUILD ASTRO ===\n`);
+  const astroConfig: string = resolve(pkgRoot, 'astro.config.mjs');
+  if (existsSync(astroConfig)) {
+    try {
+      const { build: astroBuild } = await import('astro');
+      await astroBuild({ root: pkgRoot, logLevel: 'info' });
+    } catch (e: unknown) {
+      const msg = e instanceof Error ? e.message : String(e);
+      console.warn(`  Astro build failed (${msg}), falling back to Vite SPA`);
+      console.log(`\n=== BUILD SPA ===\n`);
+      const viteConfig: string = resolve(pkgRoot, 'vite.config.ts');
+      const { build: viteBuild } = await import('vite');
+      await viteBuild({ configFile: viteConfig, root: pkgRoot, mode: 'production' });
+    }
+  } else {
+    console.log(`\n=== BUILD SPA ===\n`);
+    const viteConfig: string = resolve(pkgRoot, 'vite.config.ts');
+    const { build: viteBuild } = await import('vite');
+    await viteBuild({ configFile: viteConfig, root: pkgRoot, mode: 'production' });
+  }
+
+  const postbuild: string = resolve(pkgRoot, 'scripts', 'generate-404.js');
+  if (existsSync(postbuild)) {
+    await import(`file://${postbuild}`);
+  }
+}
+
+async function runNormalize(): Promise<void> {
+  const mod = await import('../scripts/normalize-yaml.mjs' as string);
+  const normalizeYaml = mod.normalizeYaml;
+  const check: boolean = process.argv.includes('--check');
+  const paths: string[] = process.argv.slice(2).filter(a => !a.startsWith('-') && a !== 'normalize');
+  const { checked, nonNfc, fixed }: { checked: number; nonNfc: number; fixed: string[] } = normalizeYaml({ check, paths });
+  if (check) {
+    if (nonNfc === 0) {
+      console.log(`NFC OK: ${checked} file(s) checked, all normalized`);
+      return;
+    }
+    console.error(`NFC check failed: ${nonNfc} of ${checked} file(s) are not NFC-normalized\n`);
+    for (const f of fixed) console.error(`  ${f}`);
+    process.exit(1);
+  }
+  if (nonNfc === 0) {
+    console.log(`NFC OK: ${checked} file(s) checked, all already normalized`);
+  } else {
+    console.log(`Normalized ${nonNfc} of ${checked} file(s)`);
+    for (const f of fixed) console.log(`  ${f}`);
+  }
+}
+
+async function main(): Promise<void> {
+  const args: readonly string[] = process.argv.slice(2);
+  const { positional, named }: ParsedArgs = parseArgs(args);
+  const cmd: string | undefined = positional[0];
+
+  if (!cmd || cmd === 'help' || cmd === '--help') {
+    console.log(`concept-browser <command> [options]
+
+Commands:
+  fetch      Fetch/update datasets from GCR packages or source repos
+  generate   Convert YAML concepts to JSON-LD static data
+  edges      Build cross-reference edges from generated concepts
+  about      Compile per-dataset and per-group about pages
+  build      Full pipeline (fetch + generate + edges + about + vite build)
+  site       Same as build
+  normalize  NFC-normalize YAML files in .datasets/
+  doctor     Diagnose the local environment (deps, datasets, shapes, context)
+
+Options:
+  --site <id>  Site config ID (looks for site-config.yml in CWD)
+  --check      (normalize only) Non-mutating; exit 1 if any file is not NFC
+
+Environment:
+  SITE_CONFIG          Site config file path (highest priority)
+  SITE_ID              Site config ID (same as --site)
+  GITHUB_TOKEN         GitHub token for private repos`);
+    process.exit(cmd ? 0 : 1);
+  }
+
+  if (!process.env.SITE_CONFIG && !process.env.SITE_ID && named.site) {
+    process.env.SITE_ID = named.site;
+  }
+  const { config }: { config: SiteConfig | null } = loadSiteConfig(named.site ? [named.site] : []);
+
+  if (cmd === 'build' || cmd === 'site') {
+    await runBuildPipeline(config);
+    return;
+  }
+
+  const runner: CommandRunner | undefined = commands[cmd];
+  if (runner) {
+    await runner();
+    return;
+  }
+
+  if (cmd === 'normalize') {
+    await runNormalize();
+    return;
+  }
+
+  if (cmd === 'doctor') {
+    const mod = await import('../scripts/doctor.mjs' as string);
+    await mod.main();
+    return;
+  }
+
+  console.error(`Unknown command: ${cmd}`);
+  console.error('Run `concept-browser help` for usage.');
+  process.exit(1);
+}
+
+main().catch((e: unknown) => {
+  console.error(e);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glossarist/concept-browser",
-  "version": "0.7.100",
+  "version": "0.7.102",
   "description": "Vue SPA for browsing Glossarist terminology datasets with cross-reference resolution, graph visualization, and multi-language support",
   "type": "module",
   "bin": {
@@ -37,7 +37,7 @@
     "astro": "^7.0.7",
     "d3": "^7.9.0",
     "favicons": "^7.2.0",
-    "glossarist": "^0.4.34",
+    "glossarist": "^0.4.51",
     "js-yaml": "^4.1.0",
     "jszip": "^3.10.1",
     "pinia": "^2.3.1",
@@ -59,6 +59,7 @@
     "happy-dom": "^20.9.0",
     "n3": "^1.26.0",
     "rdf-validate-shacl": "^0.4.5",
+    "tsx": "^4.23.1",
     "typescript": "~5.7.3",
     "vitest": "^4.1.5",
     "vue-tsc": "^2.2.8"

package/src/__tests__/__fixtures__/concepts.ts

@@ -87,8 +87,8 @@ function withSources(): Concept {
         type: 'authoritative',
         modification: 'revised 2024',
         origin: {
-          ref: { source: 'ISO 704', id: '3.1', version: '2020' },
-          locality: { type: 'clause', referenceFrom: '3.1', referenceTo: '3.5' },
+          ref: { source: 'ISO 704', id: '3.1', version: '2020' } as any,
+          locality: { type: 'clause', referenceFrom: '3.1', referenceTo: '3.5' } as any,
           link: 'https://example.org/iso-704',
           original: 'Original wording here.',
         },
@@ -98,7 +98,7 @@ function withSources(): Concept {
         type: 'lineage',
         origin: {
           ref: { source: 'IEC 60050', id: '102-01', version: '2008' },
-          locality: { type: 'clause', referenceFrom: '102-01-01' },
+          locality: { type: 'clause', referenceFrom: '102-01-01' } as any,
         },
       },
       {