npm - specra-cli - Versions diffs - 0.3.0 - Mend

specra-cli 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (172) hide show

package/templates/jbrains-docs/src/app.html ADDED Viewed

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<link rel="icon" href="%sveltekit.assets%/favicon.svg" type="image/svg+xml" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<link rel="preconnect" href="https://fonts.googleapis.com">
+		<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+		<link
+			href="https://fonts.googleapis.com/css2?family=Geist+Mono:wght@100..900&family=Geist:wght@100..900&display=swap"
+			rel="stylesheet">
+		%sveltekit.head%
+	</head>
+	<body data-sveltekit-preload-data="hover" class="font-sans antialiased">
+		<div style="display: contents">%sveltekit.body%</div>
+	</body>
+</html>

package/templates/jbrains-docs/src/params/product.ts ADDED Viewed

@@ -0,0 +1,7 @@
+/**
+ * SvelteKit param matcher for product slugs.
+ * Matches any string that does NOT look like a version (e.g., v1.0.0).
+ */
+export function match(param: string): boolean {
+  return !/^v\d/.test(param);
+}

package/templates/jbrains-docs/src/routes/+layout.server.ts ADDED Viewed

@@ -0,0 +1,14 @@
+import { getConfig, initConfig } from 'specra';
+import specraConfig from '../../specra.config.json';
+import type { LayoutServerLoad } from './$types';
+import type { SpecraConfig } from 'specra';
+initConfig(specraConfig as unknown as Partial<SpecraConfig>);
+export const prerender = true;
+export const trailingSlash = 'always';
+export const load: LayoutServerLoad = async () => {
+  const config = getConfig();
+  return { config };
+};

package/templates/jbrains-docs/src/routes/+layout.svelte ADDED Viewed

@@ -0,0 +1,21 @@
+<script lang="ts">
+  import '../app.css';
+  import { LayoutProviders } from 'specra/components';
+  import type { Snippet } from 'svelte';
+  import type { LayoutData } from './$types';
+  let { data, children }: { data: LayoutData; children: Snippet } = $props();
+</script>
+<svelte:head>
+  <title>{data?.config?.site?.title || 'Documentation'}</title>
+  <meta name="description" content={data?.config?.site?.description || 'Modern documentation platform'} />
+</svelte:head>
+{#if data?.config}
+  <LayoutProviders config={data.config}>
+    {@render children?.()}
+  </LayoutProviders>
+{:else}
+  {@render children?.()}
+{/if}

package/templates/jbrains-docs/src/routes/+page.server.ts ADDED Viewed

@@ -0,0 +1,9 @@
+import { redirect } from '@sveltejs/kit';
+import { getConfig } from 'specra';
+import type { PageServerLoad } from './$types';
+export const load: PageServerLoad = async () => {
+  const config = getConfig();
+  const activeVersion = config.site?.activeVersion || 'v1.0.0';
+  redirect(302, `/docs/${activeVersion}/home`);
+};

package/templates/jbrains-docs/src/routes/docs/[product=product]/[version]/+layout.server.ts ADDED Viewed

@@ -0,0 +1,40 @@
+import { getCachedVersions, getCachedAllDocs, getEffectiveConfig, getI18nConfig, getVersionsMeta, getProducts, loadVersionConfig } from 'specra';
+import { redirect } from '@sveltejs/kit';
+import type { LayoutServerLoad } from './$types';
+export const load: LayoutServerLoad = async ({ params }) => {
+  const { product, version } = params;
+  // Verify this is a valid product — if not, fall through to 404
+  const products = getProducts();
+  const matchedProduct = products.find(p => p.slug === product);
+  if (!matchedProduct) {
+    return {};
+  }
+  const i18nConfig = getI18nConfig();
+  const defaultLocale = i18nConfig?.defaultLocale || 'en';
+  // Block access to hidden versions — redirect to product's active version
+  const currentVersionConfig = loadVersionConfig(version, product);
+  if (currentVersionConfig?.hidden) {
+    const config = getEffectiveConfig(version, product);
+    const activeVersion = matchedProduct.config.activeVersion || config.site?.activeVersion || 'v1.0.0';
+    throw redirect(302, `/docs/${product}/${activeVersion}`);
+  }
+  const allDocs = await getCachedAllDocs(version, defaultLocale, product);
+  const versions = getCachedVersions(product);
+  const config = getEffectiveConfig(version, product);
+  const versionsMeta = getVersionsMeta(versions, product);
+  return {
+    allDocs,
+    versions,
+    versionsMeta,
+    config,
+    product,
+    products,
+    versionBanner: currentVersionConfig?.banner,
+  };
+};

package/templates/jbrains-docs/src/routes/docs/[product=product]/[version]/+page.server.ts ADDED Viewed

@@ -0,0 +1,24 @@
+import { redirect } from '@sveltejs/kit';
+import { getCachedAllDocs, getProducts } from 'specra';
+import type { PageServerLoad } from './$types';
+export const load: PageServerLoad = async ({ params }) => {
+  const { product, version } = params;
+  // Verify product exists
+  const products = getProducts();
+  const matchedProduct = products.find(p => p.slug === product);
+  if (!matchedProduct) {
+    return {};
+  }
+  const docs = await getCachedAllDocs(version, undefined, product);
+  if (docs.length === 0) {
+    const activeVersion = matchedProduct.config.activeVersion || 'v1.0.0';
+    redirect(302, `/docs/${product}/${activeVersion}`);
+  }
+  // Redirect to first doc in this product's version
+  redirect(302, `/docs/${product}/${version}/${docs[0].slug}`);
+};

package/templates/jbrains-docs/src/routes/docs/[product=product]/[version]/[...slug]/+page.server.ts ADDED Viewed

@@ -0,0 +1,131 @@
+import {
+  extractTableOfContents,
+  getAdjacentDocs,
+  isCategoryPage,
+  getCachedAllDocs,
+  getCachedDocBySlug,
+  getI18nConfig,
+  getProducts,
+} from 'specra';
+import type { PageServerLoad } from './$types';
+export const load: PageServerLoad = async ({ params }) => {
+  const { product, version, slug: slugArray } = params;
+  const slug = slugArray.replace(/\/$/, '');
+  // Verify product exists
+  const products = getProducts();
+  const matchedProduct = products.find(p => p.slug === product);
+  if (!matchedProduct) {
+    return {
+      version,
+      slug,
+      product,
+      isCategory: false,
+      isNotFound: true,
+      doc: null,
+      categoryTitle: null,
+      categoryDescription: null,
+      categoryTabGroup: undefined,
+      toc: [],
+      previous: null,
+      next: null,
+      title: 'Page Not Found',
+      description: 'The requested documentation page could not be found.',
+      ogUrl: `/docs/${product}/${version}/${slug}`,
+    };
+  }
+  const i18nConfig = getI18nConfig();
+  const slugParts = slug.split('/');
+  let locale: string | undefined;
+  if (i18nConfig && i18nConfig.locales.includes(slugParts[0])) {
+    locale = slugParts[0];
+  }
+  const allDocs = await getCachedAllDocs(version, locale, product);
+  const isCategory = isCategoryPage(slug, allDocs);
+  const doc = await getCachedDocBySlug(slug, version, product);
+  const urlPrefix = `/docs/${product}/${version}`;
+  let title = 'Page Not Found';
+  let description = 'The requested documentation page could not be found.';
+  let ogUrl = `${urlPrefix}/${slug}`;
+  if (doc) {
+    title = doc.meta.title || doc.title;
+    description = doc.meta.description || `Documentation for ${title}`;
+  }
+  if (!doc && isCategory) {
+    const categoryDoc = allDocs.find((d) => d.slug.startsWith(slug + '/'));
+    const categoryTabGroup = categoryDoc?.meta?.tab_group || categoryDoc?.categoryTabGroup;
+    const categoryTitle = slug
+      .split('/')
+      .pop()
+      ?.replace(/-/g, ' ')
+      .replace(/\b\w/g, (l) => l.toUpperCase()) || 'Category';
+    return {
+      version,
+      slug,
+      product,
+      isCategory: true,
+      isNotFound: false,
+      doc: null,
+      categoryTitle,
+      categoryDescription: 'Browse the documentation in this section.',
+      categoryTabGroup,
+      toc: [],
+      previous: null,
+      next: null,
+      title,
+      description,
+      ogUrl,
+    };
+  }
+  if (!doc) {
+    return {
+      version,
+      slug,
+      product,
+      isCategory: false,
+      isNotFound: true,
+      doc: null,
+      categoryTitle: null,
+      categoryDescription: null,
+      categoryTabGroup: undefined,
+      toc: [],
+      previous: null,
+      next: null,
+      title,
+      description,
+      ogUrl,
+    };
+  }
+  const toc = extractTableOfContents(doc.meta.content || doc.content);
+  const { previous, next } = getAdjacentDocs(slug, allDocs);
+  const showCategoryIndex = isCategory && !!doc;
+  const matchingDoc = allDocs.find((d) => d.slug === slug);
+  const currentPageTabGroup = doc.meta?.tab_group || matchingDoc?.categoryTabGroup;
+  return {
+    version,
+    slug,
+    product,
+    isCategory: showCategoryIndex,
+    isNotFound: false,
+    doc,
+    categoryTitle: null,
+    categoryDescription: null,
+    categoryTabGroup: currentPageTabGroup,
+    toc,
+    previous: previous ? { title: previous.meta.title, slug: previous.slug } : null,
+    next: next ? { title: next.meta.title, slug: next.slug } : null,
+    title,
+    description,
+    ogUrl,
+  };
+};

package/templates/jbrains-docs/src/routes/docs/[product=product]/[version]/[...slug]/+page.svelte ADDED Viewed

@@ -0,0 +1,180 @@
+<script lang="ts">
+  import {
+    TableOfContents,
+    Header,
+    TabGroups,
+    DocLayout,
+    CategoryIndex,
+    HotReloadIndicator,
+    DevModeBadge,
+    MdxHotReload,
+    MdxContent,
+    NotFoundContent,
+    SearchHighlight,
+    MobileDocLayout,
+    mdxComponents,
+  } from 'specra/components';
+  import type { PageData } from './$types';
+  let { data }: { data: PageData } = $props();
+  let allDocsCompat: any[] = $derived(data.allDocs);
+  let previousDoc = $derived(data.previous ?? undefined);
+  let nextDoc = $derived(data.next ?? undefined);
+  let categoryTitle = $derived(data.categoryTitle ?? undefined);
+  let categoryDescription = $derived(data.categoryDescription ?? undefined);
+</script>
+<svelte:head>
+  <title>{data.title}</title>
+  <meta name="description" content={data.description} />
+  <meta property="og:title" content={data.title} />
+  <meta property="og:description" content={data.description} />
+  <meta property="og:url" content={data.ogUrl} />
+  <meta property="og:site_name" content="Documentation Platform" />
+  <meta property="og:type" content="article" />
+  <meta property="og:locale" content="en_US" />
+  <meta name="twitter:card" content="summary_large_image" />
+  <meta name="twitter:title" content={data.title} />
+  <meta name="twitter:description" content={data.description} />
+  <link rel="canonical" href={data.ogUrl} />
+</svelte:head>
+{#if !data.doc && data.isCategory}
+  <!-- Category page without doc content -->
+  <MobileDocLayout
+    docs={allDocsCompat}
+    version={data.version}
+    product={data.product}
+    config={data.config}
+    activeTabGroup={data.categoryTabGroup}
+  >
+    {#snippet header()}
+      <Header currentVersion={data.version} versions={data.versions} versionsMeta={data.versionsMeta} versionBanner={data.versionBanner} config={data.config} products={data.products} currentProduct={data.product}>
+        {#snippet subheader()}
+          {#if data.config.navigation?.tabGroups && data.config.navigation.tabGroups.length > 0}
+            <TabGroups
+              tabGroups={data.config.navigation.tabGroups}
+              activeTabId={data.categoryTabGroup}
+              docs={allDocsCompat}
+              version={data.version}
+              product={data.product}
+              flush={data.config.navigation?.sidebarStyle === 'flush'}
+            />
+          {/if}
+        {/snippet}
+      </Header>
+    {/snippet}
+    <CategoryIndex
+      categoryPath={data.slug}
+      version={data.version}
+      product={data.product}
+      allDocs={allDocsCompat}
+      title={categoryTitle}
+      description={categoryDescription}
+      config={data.config}
+    />
+  </MobileDocLayout>
+  <MdxHotReload />
+  <HotReloadIndicator />
+  <DevModeBadge />
+{:else if data.isNotFound}
+  <!-- Not found -->
+  <MobileDocLayout
+    docs={allDocsCompat}
+    version={data.version}
+    product={data.product}
+    config={data.config}
+  >
+    {#snippet header()}
+      <Header currentVersion={data.version} versions={data.versions} versionsMeta={data.versionsMeta} versionBanner={data.versionBanner} config={data.config} products={data.products} currentProduct={data.product}>
+        {#snippet subheader()}
+          {#if data.config.navigation?.tabGroups && data.config.navigation.tabGroups.length > 0}
+            <TabGroups
+              tabGroups={data.config.navigation.tabGroups}
+              activeTabId={data.categoryTabGroup}
+              docs={allDocsCompat}
+              version={data.version}
+              product={data.product}
+              flush={data.config.navigation?.sidebarStyle === 'flush'}
+            />
+          {/if}
+        {/snippet}
+      </Header>
+    {/snippet}
+    <NotFoundContent version={data.version} />
+  </MobileDocLayout>
+  <MdxHotReload />
+  <HotReloadIndicator />
+  <DevModeBadge />
+{:else if data.doc}
+  <!-- Normal doc or category with doc content -->
+  <MobileDocLayout
+    docs={allDocsCompat}
+    version={data.version}
+    product={data.product}
+    config={data.config}
+    activeTabGroup={data.categoryTabGroup}
+  >
+    {#snippet header()}
+      <Header currentVersion={data.version} versions={data.versions} versionsMeta={data.versionsMeta} versionBanner={data.versionBanner} config={data.config} products={data.products} currentProduct={data.product}>
+        {#snippet subheader()}
+          {#if data.config.navigation?.tabGroups && data.config.navigation.tabGroups.length > 0}
+            <TabGroups
+              tabGroups={data.config.navigation.tabGroups}
+              activeTabId={data.categoryTabGroup}
+              docs={allDocsCompat}
+              version={data.version}
+              product={data.product}
+              flush={data.config.navigation?.sidebarStyle === 'flush'}
+            />
+          {/if}
+        {/snippet}
+      </Header>
+    {/snippet}
+    {#snippet toc()}
+      {#if !data.isCategory}
+        <TableOfContents items={data.toc} config={data.config} />
+      {/if}
+    {/snippet}
+    {#if data.isCategory}
+      {#snippet categoryContent()}
+        {#if data.doc?.contentNodes}
+          <MdxContent nodes={data.doc.contentNodes} components={mdxComponents} />
+        {:else if data.doc?.content}
+          {@html data.doc.content}
+        {/if}
+      {/snippet}
+      <CategoryIndex
+        categoryPath={data.slug}
+        version={data.version}
+        allDocs={allDocsCompat}
+        title={data.doc.meta.title}
+        description={data.doc.meta.description}
+        content={categoryContent}
+        config={data.config}
+      />
+    {:else}
+      <SearchHighlight />
+      <DocLayout
+        meta={data.doc.meta}
+        previousDoc={previousDoc}
+        nextDoc={nextDoc}
+        version={data.version}
+        slug={data.slug}
+        product={data.product}
+        config={data.config}
+      >
+        {#if data.doc.contentNodes}
+          <MdxContent nodes={data.doc.contentNodes} components={mdxComponents} />
+        {:else}
+          {@html data.doc.content}
+        {/if}
+      </DocLayout>
+    {/if}
+  </MobileDocLayout>
+  <MdxHotReload />
+  <HotReloadIndicator />
+  <DevModeBadge />
+{/if}

package/templates/jbrains-docs/src/routes/docs/[version]/+layout.server.ts ADDED Viewed

@@ -0,0 +1,42 @@
+import { getCachedVersions, getCachedAllDocs, getEffectiveConfig, getI18nConfig, getVersionsMeta, getProducts, loadVersionConfig } from 'specra';
+import { redirect } from '@sveltejs/kit';
+import type { LayoutServerLoad } from './$types';
+export const load: LayoutServerLoad = async ({ params }) => {
+  const { version } = params;
+  // Route disambiguation: if this "version" is actually a product slug,
+  // the +page.server.ts will handle the redirect. The layout still needs
+  // to return data for the version case.
+  const products = getProducts();
+  const isProduct = products.some(p => p.slug === version);
+  if (isProduct) {
+    // Return minimal data — the page will redirect before rendering
+    return { allDocs: [], versions: [], versionsMeta: [], config: getEffectiveConfig(''), products };
+  }
+  const i18nConfig = getI18nConfig();
+  const defaultLocale = i18nConfig?.defaultLocale || 'en';
+  // Block access to hidden versions — redirect to active version
+  const currentVersionConfig = loadVersionConfig(version);
+  if (currentVersionConfig?.hidden) {
+    const config = getEffectiveConfig(version);
+    const activeVersion = config.site?.activeVersion || 'v1.0.0';
+    throw redirect(302, `/docs/${activeVersion}`);
+  }
+  const allDocs = await getCachedAllDocs(version, defaultLocale);
+  const versions = getCachedVersions();
+  const config = getEffectiveConfig(version);
+  const versionsMeta = getVersionsMeta(versions);
+  return {
+    allDocs,
+    versions,
+    versionsMeta,
+    config,
+    products,
+    versionBanner: currentVersionConfig?.banner,
+  };
+};

package/templates/jbrains-docs/src/routes/docs/[version]/+page.server.ts ADDED Viewed

@@ -0,0 +1,27 @@
+import { redirect } from '@sveltejs/kit';
+import { getCachedVersions, getCachedAllDocs, getProducts, getEffectiveConfig } from 'specra';
+import type { PageServerLoad } from './$types';
+export const load: PageServerLoad = async ({ params }) => {
+  const { version } = params;
+  // Route disambiguation: check if this "version" is actually a product slug
+  const products = getProducts();
+  const matchedProduct = products.find(p => p.slug === version);
+  if (matchedProduct) {
+    // This is /docs/{product} — redirect to the product's active version
+    const config = getEffectiveConfig('', version);
+    const activeVersion = matchedProduct.config.activeVersion || config.site?.activeVersion || 'v1.0.0';
+    redirect(302, `/docs/${version}/${activeVersion}`);
+  }
+  // Standard version route
+  const docs = await getCachedAllDocs(version);
+  if (docs.length === 0) {
+    redirect(302, '/docs/v1.0.0');
+  }
+  // Redirect to first doc
+  redirect(302, `/docs/${version}/${docs[0].slug}`);
+};

package/templates/jbrains-docs/src/routes/docs/[version]/[...slug]/+page.server.ts ADDED Viewed

@@ -0,0 +1,106 @@
+import {
+  extractTableOfContents,
+  getAdjacentDocs,
+  isCategoryPage,
+  getCachedAllDocs,
+  getCachedDocBySlug,
+  getI18nConfig,
+} from 'specra';
+import type { PageServerLoad } from './$types';
+export const load: PageServerLoad = async ({ params }) => {
+  const { version, slug: slugArray } = params;
+  const slug = slugArray.replace(/\/$/, '');
+  const i18nConfig = getI18nConfig();
+  const slugParts = slug.split('/');
+  let locale: string | undefined;
+  if (i18nConfig && i18nConfig.locales.includes(slugParts[0])) {
+    locale = slugParts[0];
+  }
+  const allDocs = await getCachedAllDocs(version, locale);
+  const isCategory = isCategoryPage(slug, allDocs);
+  const doc = await getCachedDocBySlug(slug, version);
+  let title = 'Page Not Found';
+  let description = 'The requested documentation page could not be found.';
+  let ogUrl = `/docs/${version}/${slug}`;
+  if (doc) {
+    title = doc.meta.title || doc.title;
+    description = doc.meta.description || `Documentation for ${title}`;
+  }
+  // Category page without doc content
+  if (!doc && isCategory) {
+    const categoryDoc = allDocs.find((d) => d.slug.startsWith(slug + '/'));
+    const categoryTabGroup = categoryDoc?.meta?.tab_group || categoryDoc?.categoryTabGroup;
+    const categoryTitle = slug
+      .split('/')
+      .pop()
+      ?.replace(/-/g, ' ')
+      .replace(/\b\w/g, (l) => l.toUpperCase()) || 'Category';
+    return {
+      version,
+      slug,
+      isCategory: true,
+      isNotFound: false,
+      doc: null,
+      categoryTitle,
+      categoryDescription: 'Browse the documentation in this section.',
+      categoryTabGroup,
+      toc: [],
+      previous: null,
+      next: null,
+      title,
+      description,
+      ogUrl,
+    };
+  }
+  // Not found
+  if (!doc) {
+    return {
+      version,
+      slug,
+      isCategory: false,
+      isNotFound: true,
+      doc: null,
+      categoryTitle: null,
+      categoryDescription: null,
+      categoryTabGroup: undefined,
+      toc: [],
+      previous: null,
+      next: null,
+      title,
+      description,
+      ogUrl,
+    };
+  }
+  // Normal doc page
+  const toc = extractTableOfContents(doc.meta.content || doc.content);
+  const { previous, next } = getAdjacentDocs(slug, allDocs);
+  const showCategoryIndex = isCategory && !!doc;
+  const matchingDoc = allDocs.find((d) => d.slug === slug);
+  const currentPageTabGroup = doc.meta?.tab_group || matchingDoc?.categoryTabGroup;
+  return {
+    version,
+    slug,
+    isCategory: showCategoryIndex,
+    isNotFound: false,
+    doc,
+    categoryTitle: null,
+    categoryDescription: null,
+    categoryTabGroup: currentPageTabGroup,
+    toc,
+    previous: previous ? { title: previous.meta.title, slug: previous.slug } : null,
+    next: next ? { title: next.meta.title, slug: next.slug } : null,
+    title,
+    description,
+    ogUrl,
+  };
+};