@icebreakers/monorepo-templates 1.2.0 → 1.3.0

package/templates/vitepress/.vitepress/home/types.ts

@@ -0,0 +1,65 @@
+export interface HomeLink {
+  label: string
+  href: string
+}
+
+export interface HomeStep {
+  title: string
+  body: string
+  command: string
+}
+
+export interface HomeContent {
+  hero: {
+    label: string
+    title: string
+    description: string
+    primary: HomeLink
+    secondary: HomeLink
+    imageAlt: string
+  }
+  proof: string[]
+  lifecycle: {
+    title: string
+    description: string
+    steps: HomeStep[]
+  }
+  paths: {
+    title: string
+    description: string
+    items: Array<{
+      title: string
+      body: string
+      commands: string[]
+      href: string
+      linkLabel: string
+    }>
+  }
+  capabilities: {
+    title: string
+    description: string
+    items: Array<{ title: string, body: string }>
+  }
+  commands: {
+    title: string
+    description: string
+    items: Array<{ command: string, purpose: string }>
+  }
+  automation: {
+    title: string
+    description: string
+    formats: string[]
+    code: string
+  }
+  quickstart: {
+    title: string
+    description: string
+    code: string
+    link: HomeLink
+  }
+  docs: {
+    title: string
+    description: string
+    items: Array<HomeLink & { body: string }>
+  }
+}

package/templates/vitepress/.vitepress/navigation/routes.ts

@@ -0,0 +1,138 @@
+import type { DefaultTheme } from 'vitepress'
+
+export type DocsLocale = 'en' | 'zh'
+
+interface LocalizedText {
+  en: string
+  zh: string
+}
+
+interface RouteItem {
+  slug: string
+  label: LocalizedText
+}
+
+interface RouteSection {
+  id: 'repoctl' | 'monorepo' | 'why' | 'ai' | 'tools'
+  label: LocalizedText
+  items: RouteItem[]
+}
+
+const item = (slug: string, en: string, zh: string): RouteItem => ({ slug, label: { en, zh } })
+
+export const routeSections = [
+  {
+    id: 'repoctl',
+    label: { en: 'repoctl', zh: 'repoctl' },
+    items: [
+      item('', 'Overview', '概览'),
+      item('getting-started', 'Getting Started', '快速开始'),
+      item('adopt-existing', 'Adopt Existing Repos', '接入已有仓库'),
+      item('scenarios', 'Choose By Scenario', '按场景选命令'),
+      item('execution-model', 'Execution Model', '执行模型'),
+      item('commands', 'Command Reference', '命令速查'),
+      item('checks', 'Verification', '校验链路'),
+      item('doctor', 'Doctor', 'Doctor 诊断'),
+      item('config', 'Configuration', '配置文件'),
+      item('templates', 'Templates', '模板与创建'),
+      item('template-assets', 'Template Assets', '模板资产治理'),
+      item('workflows', 'Workflows and CI', '工作流与 CI'),
+      item('reports', 'Reports', '报告与自动化输出'),
+      item('troubleshooting', 'Troubleshooting', '排障'),
+      item('aliases', 'Command Aliases', '命令别名'),
+    ],
+  },
+  {
+    id: 'monorepo',
+    label: { en: 'Knowledge Base', zh: '知识库' },
+    items: [
+      item('', 'Why Monorepo', '为什么使用 Monorepo'),
+      item('manage', 'Managing A Monorepo', '管理 Monorepo'),
+      item('publish', 'Publishing and Changelogs', '发包与变更日志'),
+      item('commands', 'Monorepo Commands', 'Monorepo 命令'),
+      item('templates', 'Template Systems', '模板体系'),
+      item('troubleshooting', 'Troubleshooting', '常见问题排障'),
+    ],
+  },
+  {
+    id: 'why',
+    label: { en: 'Modern Packages', zh: '现代 npm 包' },
+    items: [
+      item('how-to-reuse-js-code', 'Reusing JavaScript', '复用 JavaScript'),
+      item('js-cjs-mjs', 'Module Extensions', '模块文件后缀'),
+      item('js-keywords', 'Runtime Globals', '运行时关键字'),
+      item('what-is-npm-package', 'What Is An npm Package?', '什么是 npm 包'),
+      item('publish-basic-npm-package', 'Publishing A Package', '发布 npm 包'),
+      item('', 'Package Evolution', '包的演进'),
+      item('modern/', 'Modern Package Guide', '现代包指南'),
+      item('modern/esm-vs-cjs', 'ESM vs CommonJS', 'ESM 与 CommonJS'),
+      item('modern/dts', 'Type Declarations', '类型声明'),
+      item('modern/package-entry-points', 'Package Entry Points', '包入口'),
+      item('modern/bundlers', 'Bundlers', '构建工具'),
+      item('modern/typescript', 'TypeScript', 'TypeScript'),
+    ],
+  },
+  {
+    id: 'ai',
+    label: { en: 'AI', zh: 'AI' },
+    items: [item('', 'AI Documentation', 'AI 文档'), item('llms-txt', 'llms.txt', 'llms.txt')],
+  },
+  {
+    id: 'tools',
+    label: { en: 'Tool Guides', zh: '工具专题' },
+    items: [
+      item('', 'Overview', '概览'),
+      item('pnpm', 'pnpm', 'pnpm'),
+      item('turborepo', 'Turborepo', 'Turborepo'),
+      item('changeset', 'pnpm Versioning', 'pnpm Versioning'),
+      item('husky', 'Husky', 'Husky'),
+      item('lint-staged', 'lint-staged', 'lint-staged'),
+      item('renovate', 'Renovate', 'Renovate'),
+      item('llms-txt', 'llms.txt', 'llms.txt'),
+    ],
+  },
+] as const satisfies readonly RouteSection[]
+
+function prefixFor(locale: DocsLocale) {
+  return locale === 'zh' ? '/zh' : ''
+}
+
+function sectionItems(section: RouteSection, locale: DocsLocale): DefaultTheme.SidebarItem[] {
+  const prefix = prefixFor(locale)
+  return section.items.map(route => ({
+    text: route.label[locale],
+    link: `${prefix}/${section.id}/${route.slug}`.replace(/\/+/g, '/'),
+  }))
+}
+
+export function createSidebars(locale: DocsLocale): DefaultTheme.SidebarMulti {
+  const prefix = prefixFor(locale)
+  const groups = Object.fromEntries(routeSections.map(section => [
+    section.id,
+    { text: section.label[locale], items: sectionItems(section, locale) },
+  ])) as Record<RouteSection['id'], DefaultTheme.SidebarItem>
+  const knowledge = [groups.monorepo, groups.why]
+
+  return {
+    [`${prefix}/repoctl/`]: [groups.repoctl],
+    [`${prefix}/knowledge/`]: knowledge,
+    [`${prefix}/monorepo/`]: knowledge,
+    [`${prefix}/why/`]: knowledge,
+    [`${prefix}/ai/`]: [groups.ai],
+    [`${prefix}/tools/`]: [groups.tools],
+    [`${prefix || ''}/`]: [groups.repoctl],
+  }
+}
+
+export function createNav(locale: DocsLocale): DefaultTheme.NavItem[] {
+  const zh = locale === 'zh'
+  const prefix = prefixFor(locale)
+  return [
+    { text: 'repoctl', link: `${prefix}/repoctl/` },
+    { text: zh ? '快速开始' : 'Getting Started', link: `${prefix}/repoctl/getting-started` },
+    { text: zh ? '命令' : 'Commands', link: `${prefix}/repoctl/commands` },
+    { text: zh ? '知识库' : 'Knowledge Base', link: `${prefix}/knowledge/` },
+    { text: zh ? 'AI 文档' : 'AI Docs', link: `${prefix}/ai/` },
+    { text: zh ? '工具专题' : 'Tool Guides', link: `${prefix}/tools/` },
+  ]
+}

package/templates/vitepress/.vitepress/seo.ts

@@ -0,0 +1,40 @@
+import type { HeadConfig, TransformContext } from 'vitepress'
+
+export const siteOrigin = 'https://repoctl.icebreaker.top'
+
+function routeFromPage(page: string) {
+  const withoutExtension = page.replace(/\.md$/, '')
+  if (withoutExtension === 'index') {
+    return '/'
+  }
+  if (withoutExtension.endsWith('/index')) {
+    return `/${withoutExtension.slice(0, -6)}`
+  }
+  return `/${withoutExtension}`
+}
+
+function localeRoutes(page: string) {
+  const sourcePage = page.startsWith('zh/') ? page.slice(3) : page
+  const english = routeFromPage(sourcePage)
+  const chinese = routeFromPage(`zh/${sourcePage}`)
+  return { english, chinese }
+}
+
+export function createPageHead({ page, title, description }: TransformContext): HeadConfig[] {
+  const { english, chinese } = localeRoutes(page)
+  const current = page.startsWith('zh/') ? chinese : english
+  const canonical = `${siteOrigin}${current}`
+
+  return [
+    ['link', { rel: 'canonical', href: canonical }],
+    ['link', { rel: 'alternate', hreflang: 'en', href: `${siteOrigin}${english}` }],
+    ['link', { rel: 'alternate', hreflang: 'zh-CN', href: `${siteOrigin}${chinese}` }],
+    ['link', { rel: 'alternate', hreflang: 'x-default', href: `${siteOrigin}${english}` }],
+    ['meta', { property: 'og:type', content: 'website' }],
+    ['meta', { property: 'og:site_name', content: 'repoctl' }],
+    ['meta', { property: 'og:title', content: title }],
+    ['meta', { property: 'og:description', content: description }],
+    ['meta', { property: 'og:url', content: canonical }],
+    ['meta', { property: 'og:locale', content: page.startsWith('zh/') ? 'zh_CN' : 'en_US' }],
+  ]
+}

package/templates/vitepress/.vitepress/theme/components/HomePage.vue

@@ -0,0 +1,134 @@
+<script setup lang="ts">
+import type { DocsLocale } from '../../navigation/routes'
+import { computed } from 'vue'
+import { homeContent } from '../../home/content'
+
+const props = defineProps<{ locale: DocsLocale }>()
+const content = computed(() => homeContent[props.locale])
+</script>
+
+<template>
+  <main class="repoctl-home">
+    <section class="repoctl-home__hero">
+      <div class="repoctl-home__hero-copy">
+        <p class="repoctl-home__eyebrow">
+          {{ content.hero.label }}
+        </p>
+        <h1>{{ content.hero.title }}</h1>
+        <p class="repoctl-home__lede">
+          {{ content.hero.description }}
+        </p>
+        <div class="repoctl-home__actions">
+          <a class="repoctl-home__button repoctl-home__button--primary" :href="content.hero.primary.href">
+            {{ content.hero.primary.label }}
+          </a>
+          <a class="repoctl-home__button" :href="content.hero.secondary.href">
+            {{ content.hero.secondary.label }}
+          </a>
+        </div>
+      </div>
+      <figure class="repoctl-home__capture">
+        <img src="/repoctl-doctor.png" :alt="content.hero.imageAlt" width="1440" height="990">
+      </figure>
+    </section>
+
+    <section class="repoctl-home__proof" :aria-label="locale === 'en' ? 'repoctl capabilities' : 'repoctl 能力'">
+      <span v-for="item in content.proof" :key="item">{{ item }}</span>
+    </section>
+
+    <section class="repoctl-home__section repoctl-home__lifecycle">
+      <div class="repoctl-home__section-heading">
+        <h2>{{ content.lifecycle.title }}</h2>
+        <p>{{ content.lifecycle.description }}</p>
+      </div>
+      <ol>
+        <li v-for="step in content.lifecycle.steps" :key="step.command">
+          <code>{{ step.command }}</code>
+          <h3>{{ step.title }}</h3>
+          <p>{{ step.body }}</p>
+        </li>
+      </ol>
+    </section>
+
+    <section class="repoctl-home__section repoctl-home__paths">
+      <div class="repoctl-home__section-heading">
+        <h2>{{ content.paths.title }}</h2>
+        <p>{{ content.paths.description }}</p>
+      </div>
+      <div class="repoctl-home__path-grid">
+        <article v-for="item in content.paths.items" :key="item.href">
+          <h3>{{ item.title }}</h3>
+          <p>{{ item.body }}</p>
+          <pre><code>{{ item.commands.join('\n') }}</code></pre>
+          <a :href="item.href">{{ item.linkLabel }}</a>
+        </article>
+      </div>
+    </section>
+
+    <section class="repoctl-home__section repoctl-home__capabilities">
+      <div class="repoctl-home__section-heading">
+        <p class="repoctl-home__eyebrow">
+          repoctl
+        </p>
+        <h2>{{ content.capabilities.title }}</h2>
+        <p>{{ content.capabilities.description }}</p>
+      </div>
+      <div class="repoctl-home__capability-grid">
+        <article v-for="item in content.capabilities.items" :key="item.title">
+          <h3>{{ item.title }}</h3>
+          <p>{{ item.body }}</p>
+        </article>
+      </div>
+    </section>
+
+    <section class="repoctl-home__section repoctl-home__commands">
+      <div class="repoctl-home__section-heading">
+        <h2>{{ content.commands.title }}</h2>
+        <p>{{ content.commands.description }}</p>
+      </div>
+      <dl>
+        <div v-for="item in content.commands.items" :key="item.command">
+          <dt><code>{{ item.command }}</code></dt>
+          <dd>{{ item.purpose }}</dd>
+        </div>
+      </dl>
+    </section>
+
+    <section class="repoctl-home__section repoctl-home__automation">
+      <div>
+        <h2>{{ content.automation.title }}</h2>
+        <p>{{ content.automation.description }}</p>
+        <ul>
+          <li v-for="format in content.automation.formats" :key="format">
+            {{ format }}
+          </li>
+        </ul>
+      </div>
+      <pre><code>{{ content.automation.code }}</code></pre>
+    </section>
+
+    <section class="repoctl-home__section repoctl-home__quickstart">
+      <div class="repoctl-home__section-heading">
+        <h2>{{ content.quickstart.title }}</h2>
+        <p>{{ content.quickstart.description }}</p>
+      </div>
+      <pre><code>{{ content.quickstart.code }}</code></pre>
+      <a class="repoctl-home__button repoctl-home__button--primary" :href="content.quickstart.link.href">
+        {{ content.quickstart.link.label }}
+      </a>
+    </section>
+
+    <section class="repoctl-home__section repoctl-home__docs">
+      <div class="repoctl-home__section-heading">
+        <h2>{{ content.docs.title }}</h2>
+        <p>{{ content.docs.description }}</p>
+      </div>
+      <div>
+        <a v-for="item in content.docs.items" :key="item.href" :href="item.href">
+          <strong>{{ item.label }}</strong>
+          <span>{{ item.body }}</span>
+        </a>
+      </div>
+    </section>
+  </main>
+</template>

package/templates/vitepress/.vitepress/theme/home/foundation.css

@@ -0,0 +1,180 @@
+.repoctl-home {
+  --home-border: color-mix(in srgb, var(--vp-c-divider) 82%, transparent);
+  --home-accent: #1769aa;
+  --home-accent-dark: #4aa3e0;
+  --home-muted: var(--vp-c-text-2);
+
+  max-width: 1180px;
+  padding: 32px 24px 96px;
+  margin: 0 auto;
+  color: var(--vp-c-text-1);
+}
+
+.repoctl-home h1,
+.repoctl-home h2,
+.repoctl-home h3,
+.repoctl-home p,
+.repoctl-home figure,
+.repoctl-home pre {
+  margin: 0;
+}
+
+.repoctl-home__hero {
+  display: grid;
+  grid-template-columns: minmax(0, 0.88fr) minmax(420px, 1.12fr);
+  gap: clamp(32px, 5vw, 72px);
+  align-items: center;
+  min-height: min(680px, calc(100dvh - 96px));
+}
+
+.repoctl-home__eyebrow {
+  margin-bottom: 14px !important;
+  font-size: 12px;
+  font-weight: 700;
+  color: var(--home-accent);
+  letter-spacing: 0;
+}
+
+.dark .repoctl-home__eyebrow {
+  color: var(--home-accent-dark);
+}
+
+.repoctl-home__hero h1 {
+  max-width: 13ch;
+  font-size: clamp(42px, 4.25vw, 60px);
+  line-height: 1.02;
+  letter-spacing: 0;
+}
+
+.repoctl-home__lede,
+.repoctl-home__section-heading > p,
+.repoctl-home article p,
+.repoctl-home__automation p {
+  line-height: 1.7;
+  color: var(--home-muted);
+}
+
+.repoctl-home__lede {
+  max-width: 38rem;
+  margin-top: 22px !important;
+  font-size: 17px;
+}
+
+.repoctl-home__actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+  margin-top: 28px;
+}
+
+.repoctl-home__button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 42px;
+  padding: 0 17px;
+  font-size: 14px;
+  font-weight: 650;
+  color: var(--vp-c-text-1) !important;
+  text-decoration: none !important;
+  border: 1px solid var(--home-border);
+  border-radius: 6px;
+  transition:
+    transform 180ms ease,
+    border-color 180ms ease,
+    background-color 180ms ease;
+}
+
+.repoctl-home__button:hover {
+  border-color: var(--home-accent);
+  transform: translateY(-1px);
+}
+
+.repoctl-home__button:active {
+  transform: translateY(0);
+}
+
+.repoctl-home__button--primary {
+  color: #fff !important;
+  background: var(--home-accent);
+  border-color: var(--home-accent);
+}
+
+.repoctl-home__capture {
+  overflow: hidden;
+  background: #111a23;
+  border: 1px solid var(--home-border);
+  border-radius: 6px;
+  box-shadow: 0 22px 56px rgb(23 105 170 / 16%);
+}
+
+.repoctl-home__capture img {
+  display: block;
+  width: 100%;
+  height: auto;
+}
+
+.repoctl-home__proof {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px 26px;
+  padding: 20px 0;
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--home-muted);
+  border-top: 1px solid var(--home-border);
+  border-bottom: 1px solid var(--home-border);
+}
+
+.repoctl-home__section {
+  padding-top: 96px;
+}
+
+.repoctl-home__section-heading {
+  max-width: 680px;
+  margin-bottom: 32px;
+}
+
+.repoctl-home__section-heading h2,
+.repoctl-home__automation h2 {
+  font-size: clamp(28px, 3vw, 40px);
+  line-height: 1.12;
+  letter-spacing: 0;
+}
+
+.repoctl-home__section-heading > p,
+.repoctl-home__automation p {
+  margin-top: 12px !important;
+}
+
+.repoctl-home__lifecycle ol {
+  display: grid;
+  grid-template-columns: repeat(5, 1fr);
+  gap: 16px;
+  padding: 0;
+  list-style: none;
+}
+
+.repoctl-home__lifecycle li {
+  min-height: 184px;
+  padding: 18px;
+  border: 1px solid var(--home-border);
+  border-radius: 6px;
+}
+
+.repoctl-home code {
+  font-size: 0.86em;
+}
+
+.repoctl-home__lifecycle h3,
+.repoctl-home__capability-grid h3 {
+  margin-top: 22px;
+  font-size: 17px;
+}
+
+.repoctl-home__lifecycle p {
+  margin-top: 8px !important;
+  font-size: 14px;
+  line-height: 1.6;
+  color: var(--home-muted);
+}

package/templates/vitepress/.vitepress/theme/home/index.css

@@ -0,0 +1,3 @@
+@import './foundation.css';
+@import './sections.css';
+@import './responsive.css';

package/templates/vitepress/.vitepress/theme/home/responsive.css

@@ -0,0 +1,49 @@
+@media (max-width: 900px) {
+  .repoctl-home__hero,
+  .repoctl-home__quickstart {
+    grid-template-columns: 1fr;
+    min-height: auto;
+    padding-top: 42px;
+  }
+
+  .repoctl-home__quickstart .repoctl-home__button {
+    grid-column: auto;
+  }
+
+  .repoctl-home__lifecycle ol {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+
+@media (max-width: 640px) {
+  .repoctl-home {
+    padding: 16px 20px 68px;
+  }
+
+  .repoctl-home__hero h1 {
+    font-size: 42px;
+  }
+
+  .repoctl-home__section {
+    padding-top: 64px;
+  }
+
+  .repoctl-home__lifecycle ol,
+  .repoctl-home__path-grid,
+  .repoctl-home__automation,
+  .repoctl-home__commands dl,
+  .repoctl-home__docs > div,
+  .repoctl-home__capability-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .repoctl-home__automation {
+    padding: 24px;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .repoctl-home__button {
+    transition: none;
+  }
+}