@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/scripts/generate-docs/lib/sidebar-builder.ts

@@ -0,0 +1,80 @@
+/**
+ * scripts/generate-docs/lib/sidebar-builder.ts
+ *
+ * Reads `docs-src/_data/sidebar.json`, validates that every referenced page
+ * exists in `docs-src/*.md`, and returns a per-page enriched copy with the
+ * `active` flag injected on the current page entry.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { LocalisedString } from './markdown-parser';
+
+const SIDEBAR_PATH = join(__dirname, '..', '..', '..', 'docs-src', '_data', 'sidebar.json');
+
+export interface SidebarItem {
+  page: string;
+  icon: string;
+  label: LocalisedString;
+  active?: boolean;
+  /** Optional nested entries rendered indented below the parent. */
+  children?: SidebarItem[];
+}
+
+export interface SidebarSection {
+  title: LocalisedString;
+  items: SidebarItem[];
+}
+
+export interface Sidebar {
+  sections: SidebarSection[];
+}
+
+let cached: Sidebar | null = null;
+
+function loadSidebar(): Sidebar {
+  if (cached) return cached;
+  const raw = readFileSync(SIDEBAR_PATH, 'utf-8');
+  cached = JSON.parse(raw) as Sidebar;
+  return cached;
+}
+
+/**
+ * Throws if any sidebar entry points to a page slug that wasn't found among
+ * the parsed pages — catches "added link to sidebar but never to docs-src".
+ * Recurses into `children`.
+ */
+export function validateSidebar(knownSlugs: string[]): void {
+  const sidebar = loadSidebar();
+  const known = new Set(knownSlugs);
+  const missing: string[] = [];
+  const visit = (item: SidebarItem): void => {
+    if (!known.has(item.page)) missing.push(item.page);
+    item.children?.forEach(visit);
+  };
+  for (const section of sidebar.sections) section.items.forEach(visit);
+  if (missing.length) {
+    throw new Error(
+      `sidebar.json references pages that have no docs-src/<slug>.md: ${missing.join(', ')}`
+    );
+  }
+}
+
+/**
+ * Returns a deep-cloned sidebar with `active: true` set on the item (or nested
+ * child) whose `page` matches the current page slug. Cloning keeps each page
+ * render independent.
+ */
+export function buildSidebarForPage(currentSlug: string): Sidebar {
+  const sidebar = loadSidebar();
+  const cloneItem = (item: SidebarItem): SidebarItem => ({
+    ...item,
+    active: item.page === currentSlug,
+    children: item.children?.map(cloneItem),
+  });
+  return {
+    sections: sidebar.sections.map((section) => ({
+      title: section.title,
+      items: section.items.map(cloneItem),
+    })),
+  };
+}

package/scripts/generate-docs/lib/skill-parser.ts

@@ -0,0 +1,171 @@
+/**
+ * scripts/generate-docs/lib/skill-parser.ts
+ *
+ * Walks every `templates/skills/**\/SKILL.md`, parses the YAML frontmatter via
+ * gray-matter, and returns a normalised `Skill[]` ready for Handlebars context
+ * building. Slugs and phase buckets come from the shared
+ * `templates/skills/lib/skill-slug.ts` helpers so that the doc generator
+ * cannot drift from the installer.
+ */
+import { readFileSync } from 'node:fs';
+import { join, relative, dirname, basename } from 'node:path';
+import { sync as globSync } from 'glob';
+import matter from 'gray-matter';
+import {
+  remapSkillPath,
+  phaseFromAuthoringPath,
+} from '../../../templates/skills/lib/skill-slug';
+
+const SKILLS_ROOT = join(__dirname, '..', '..', '..', 'templates', 'skills');
+
+export interface Skill {
+  /** Slash-command slug (e.g. `ba-audit-actors`, `efcore`, `backend-controller`) */
+  slug: string;
+  /** Frontmatter `name:` field (canonical command name) */
+  name: string;
+  /** Frontmatter `description:` (flattened to a single string) */
+  description: string;
+  /** Phase bucket: `business-analyse`, `development/backend`, `lifecycle`, … */
+  phase: string;
+  /** Optional `argument-hint:` from frontmatter */
+  argumentHint: string | null;
+  /** Optional `allowed-tools:` list (mixed string or comma-separated YAML) */
+  allowedTools: string[];
+  /** Optional `model:` (e.g. `haiku`) */
+  model: string | null;
+  /** Optional `group:` (e.g. `H` for ba-develop) */
+  group: string | null;
+  /** Path to the source SKILL.md relative to repo root, for debugging */
+  sourcePath: string;
+  /** First non-empty body line, useful for hover tooltips */
+  firstBodyLine: string;
+}
+
+/**
+ * Flatten a YAML scalar (which gray-matter may yield as a multi-line string
+ * with embedded newlines from `>` block scalars) into a single, trimmed line.
+ */
+function flatten(value: unknown): string {
+  if (value == null) return '';
+  if (typeof value !== 'string') return String(value);
+  return value.replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Coerce `allowed-tools` to a string array. YAML accepts both list and
+ * comma-separated forms; we normalise to a single shape.
+ */
+function toToolList(value: unknown): string[] {
+  if (!value) return [];
+  if (Array.isArray(value)) return value.map((v) => String(v).trim()).filter(Boolean);
+  return String(value)
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Extract the first non-empty, non-heading line from the markdown body.
+ * Used as a short summary on cards when the YAML description is unhelpfully
+ * long.
+ */
+function firstBodyLine(body: string): string {
+  for (const raw of body.split('\n')) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (line.startsWith('#')) continue; // skip headings
+    if (line.startsWith('>')) continue; // skip blockquotes
+    if (line.startsWith('---')) continue; // skip horizontal rules
+    return line.length > 200 ? line.slice(0, 197) + '…' : line;
+  }
+  return '';
+}
+
+/**
+ * Parse a single SKILL.md given its absolute path. Returns `null` for files
+ * that the installer would not deploy (BA `_workflow/` companions, BA index).
+ */
+export function parseSkillFile(absPath: string): Skill | null {
+  const rel = relative(SKILLS_ROOT, absPath).replace(/\\/g, '/');
+  const remapped = remapSkillPath(rel);
+  if (remapped === null) return null;
+
+  const raw = readFileSync(absPath, 'utf-8');
+  const parsed = matter(raw);
+  const data = parsed.data ?? {};
+
+  const name = flatten(data.name) || basename(dirname(rel));
+  const description = flatten(data.description);
+  const phase = typeof data.phase === 'string' && data.phase.trim()
+    ? data.phase.trim()
+    : phaseFromAuthoringPath(rel);
+
+  // Derive slug: prefer the remapped folder name (matches what the installer
+  // deploys); for nested skills (e.g. `development/backend/controller/`), use
+  // the YAML `name:` since only the first folder is registered by Claude Code.
+  const remappedFolder = dirname(remapped).split('/')[0];
+  const slug = name || remappedFolder;
+
+  return {
+    slug,
+    name,
+    description,
+    phase,
+    argumentHint: flatten(data['argument-hint']) || null,
+    allowedTools: toToolList(data['allowed-tools']),
+    model: flatten(data.model) || null,
+    group: flatten(data.group) || null,
+    sourcePath: `templates/skills/${rel}`,
+    firstBodyLine: firstBodyLine(parsed.content),
+  };
+}
+
+/**
+ * Walk the entire `templates/skills/` tree, parse every SKILL.md, drop the
+ * ones the installer would not deploy, and return them sorted by slug for
+ * deterministic output (the snapshot tests rely on this).
+ */
+export function parseAllSkills(): Skill[] {
+  const pattern = join(SKILLS_ROOT, '**', 'SKILL.md').replace(/\\/g, '/');
+  const files = globSync(pattern, { absolute: true });
+
+  const skills: Skill[] = [];
+  for (const file of files) {
+    const parsed = parseSkillFile(file);
+    if (parsed) skills.push(parsed);
+  }
+  skills.sort((a, b) => a.slug.localeCompare(b.slug));
+  return skills;
+}
+
+/**
+ * Group skills by their `phase` field, returning a deterministically-ordered
+ * `Record<phase, Skill[]>`. Used by Handlebars helpers downstream.
+ */
+export function groupByPhase(skills: Skill[]): Record<string, Skill[]> {
+  const out: Record<string, Skill[]> = {};
+  for (const s of skills) {
+    (out[s.phase] ??= []).push(s);
+  }
+  // Sort keys for stable rendering
+  return Object.fromEntries(
+    Object.entries(out).sort(([a], [b]) => a.localeCompare(b))
+  );
+}
+
+// CLI entry: `npx tsx scripts/generate-docs/lib/skill-parser.ts`
+// Prints a summary so we can verify the parser sees every expected skill.
+if (require.main === module) {
+  const skills = parseAllSkills();
+  const groups = groupByPhase(skills);
+  // eslint-disable-next-line no-console
+  console.log(`Parsed ${skills.length} skills from templates/skills/`);
+  for (const [phase, list] of Object.entries(groups)) {
+    // eslint-disable-next-line no-console
+    console.log(`  [${phase}] ${list.length}`);
+    for (const s of list) {
+      // eslint-disable-next-line no-console
+      console.log(`    /${s.slug}  ${s.description.slice(0, 80)}`);
+    }
+  }
+}

package/scripts/generate-docs/lib/stats.ts

@@ -0,0 +1,32 @@
+/**
+ * scripts/generate-docs/lib/stats.ts
+ * Counts the moving parts that should appear in the stats bar on index.html.
+ * Numbers are derived from the filesystem so they can never go stale.
+ */
+import { sync as globSync } from 'glob';
+import { join } from 'node:path';
+import { parseAllSkills } from './skill-parser';
+
+const REPO_ROOT = join(__dirname, '..', '..', '..');
+
+export interface Stats {
+  skills: number;
+  agents: number;
+  hooks: number;
+  cliCommands: number;
+}
+
+function count(glob: string): number {
+  return globSync(glob.replace(/\\/g, '/'), { cwd: REPO_ROOT }).length;
+}
+
+export function collectStats(): Stats {
+  return {
+    skills: parseAllSkills().length,
+    agents: count('templates/agents/*.md'),
+    hooks: count('templates/hooks/*.{sh,js,mjs,cjs}'),
+    // CLI commands = TypeScript files in src/commands/ excluding the barrel index.ts
+    cliCommands: globSync('src/commands/*.ts', { cwd: REPO_ROOT })
+      .filter((f) => !/[\\/]index\.ts$/.test(f)).length,
+  };
+}

package/scripts/generate-docs/lib/version.ts

@@ -0,0 +1,17 @@
+/**
+ * scripts/generate-docs/lib/version.ts
+ * Reads the canonical version from package.json so the doc generator can
+ * inject it into every page (kills the v3.34.0 drift permanently).
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const PKG_PATH = join(__dirname, '..', '..', '..', 'package.json');
+
+export const VERSION: string = (() => {
+  const pkg = JSON.parse(readFileSync(PKG_PATH, 'utf-8')) as { version?: string };
+  if (!pkg.version) {
+    throw new Error(`Cannot read version from ${PKG_PATH}`);
+  }
+  return pkg.version;
+})();

package/scripts/generate-docs/templates/layout.hbs

@@ -0,0 +1,33 @@
+<!DOCTYPE html>
+<!--
+  AUTO-GENERATED by scripts/generate-docs — do not edit by hand.
+  Edit docs-src/{{page.slug}}.md (or templates/skills/<skill>/SKILL.md for skill data)
+  and run `npm run build:docs`. CI enforces drift via `npm run docs:check`.
+-->
+<html lang="fr">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{i18n page.title "fr"}} - SmartStack CLI</title>
+    <link rel="stylesheet" href="css/styles.css">
+</head>
+<body>
+    <div class="app-container">
+{{> header}}
+
+        <div class="app-body">
+{{> sidebar}}
+
+            <main class="main-content">
+                <div class="content content-wide">
+{{#if page.breadcrumb}}
+{{> breadcrumb}}
+{{/if}}
+{{{bodyHtml}}}
+                </div>
+            </main>
+        </div>
+    </div>
+    <script src="js/app.js"></script>
+</body>
+</html>

package/scripts/generate-docs/templates/pages/_generic.hbs

@@ -0,0 +1,12 @@
+{{{bodyHtml}}}
+
+{{#if skillsForPage.length}}
+                <section class="skills-section">
+                    <h2 data-lang="fr">Skills disponibles</h2>
+                    <h2 data-lang="en">Available Skills</h2>
+{{#groupSkillsByPhase skillsForPage}}
+                    <h3>{{phase}}</h3>
+                    {{> skill-grid skills=skills}}
+{{/groupSkillsByPhase}}
+                </section>
+{{/if}}

package/scripts/generate-docs/templates/pages/ba-develop.hbs

@@ -0,0 +1,10 @@
+{{{bodyHtml}}}
+
+                <section class="skills-section">
+                    <h2 data-lang="fr">Skills orchestrées par <code>/ba-develop</code></h2>
+                    <h2 data-lang="en">Skills orchestrated by <code>/ba-develop</code></h2>
+{{#groupSkillsByPhase skillsForPage}}
+                    <h3 id="phase-{{slugify phase}}">{{phase}} <span class="skill-count">({{count skills}})</span></h3>
+                    {{> skill-grid skills=skills}}
+{{/groupSkillsByPhase}}
+                </section>

package/scripts/generate-docs/templates/pages/ba-skills.hbs

@@ -0,0 +1,8 @@
+{{{bodyHtml}}}
+
+                <section class="skills-section">
+{{#groupSkillsByPhase skillsForPage}}
+                    <h3 id="phase-{{slugify phase}}">{{phase}} <span class="skill-count">({{count skills}})</span></h3>
+                    {{> skill-grid skills=skills}}
+{{/groupSkillsByPhase}}
+                </section>

package/scripts/generate-docs/templates/pages/business-analyse.hbs

@@ -0,0 +1 @@
+{{{bodyHtml}}}

package/scripts/generate-docs/templates/pages/commands.hbs

@@ -0,0 +1,13 @@
+{{{bodyHtml}}}
+
+                <section class="skills-section">
+                    <h2 data-lang="fr">Table complète des skills</h2>
+                    <h2 data-lang="en">Complete skill table</h2>
+                    <p data-lang="fr">Toutes les commandes <code>/&lt;nom&gt;</code> déployées par <code>ss install</code>, groupées par phase.</p>
+                    <p data-lang="en">All <code>/&lt;name&gt;</code> commands deployed by <code>ss install</code>, grouped by phase.</p>
+
+{{#groupSkillsByPhase skillsForPage}}
+                    <h3 id="phase-{{slugify phase}}">{{phase}} <span class="skill-count">({{count skills}})</span></h3>
+                    {{> skill-grid skills=skills}}
+{{/groupSkillsByPhase}}
+                </section>