@terra-symposium/docs 0.2.0 → 0.4.0

package/bin/generate-skills.mjs

@@ -1,188 +0,0 @@
-#!/usr/bin/env node
-
-/*//////////////////////////////////////////////////
-IMPORTS
-//////////////////////////////////////////////////*/
-
-// API
-import { dirname, join, relative, resolve, sep } from 'node:path';
-import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
-import { parse } from 'yaml';
-
-/*//////////////////////////////////////////////////
-CONFIG
-//////////////////////////////////////////////////*/
-
-const ignoredDirs = new Set([
-  '.astro',
-  '.cache',
-  '.git',
-  '.next',
-  '.nuxt',
-  '.output',
-  '.svelte-kit',
-  '.turbo',
-  '.vite',
-  '.vercel',
-  '.wrangler',
-  'build',
-  'coverage',
-  'dist',
-  'docs-dist',
-  'node_modules',
-  'target',
-  'vendor',
-]);
-
-/*//////////////////////////////////////////////////
-HELPERS
-//////////////////////////////////////////////////*/
-
-/**
- * Finds skill instruction files beneath a directory, skipping generated and dependency folders.
- *
- * @param dir Directory whose descendants should be searched.
- * @param files Accumulator shared by recursive calls.
- *
- * @return Paths to the discovered `SKILL.md` files.
- */
-async function findSkillFiles(dir, files = []) {
-  const entries = await readdir(dir, { withFileTypes: true });
-  for (const entry of entries) {
-    if (entry.isDirectory() && ignoredDirs.has(entry.name)) continue;
-    const path = join(dir, entry.name);
-    if (entry.isDirectory()) await findSkillFiles(path, files);
-    else if (entry.isFile() && entry.name === 'SKILL.md') files.push(path);
-  }
-  return files;
-}
-
-/**
- * Separates a skill document's Markdown body from its optional YAML frontmatter.
- *
- * @param source Complete skill document contents.
- *
- * @return Parsed metadata and body, plus a validation issue when YAML parsing fails.
- */
-function splitFrontmatter(source) {
-  const match = /^---\s*\n([\s\S]*?)\n---\s*\n?/.exec(source);
-  if (!match) return { body: source.trim(), metadata: {}, metadataIssue: undefined };
-  try {
-    const metadata = parse(match[1]);
-    return {
-      body: source.slice(match[0].length).trim(),
-      metadata:
-        metadata && typeof metadata === 'object' && !Array.isArray(metadata) ? metadata : {},
-      metadataIssue: undefined,
-    };
-  } catch (err) {
-    return {
-      body: source.slice(match[0].length).trim(),
-      metadata: {},
-      metadataIssue: err instanceof Error ? err.message : String(err),
-    };
-  }
-}
-
-/**
- * Resolves a skill's display scope and directory from its repository-relative path.
- *
- * @param root Repository root used to make the skill path relative.
- * @param path Absolute path of the skill instruction file.
- *
- * @return Directory and scope labels for the generated index entry.
- */
-function skillLocation(root, path) {
-  const segments = relative(root, path).split(sep);
-  const skillRootIndex = segments.findIndex(
-    (segment, i) => (segment === '.agents' || segment === '.codex') && segments[i + 1] === 'skills',
-  );
-  if (skillRootIndex >= 0) {
-    const scope = segments.slice(0, skillRootIndex).join('/') || 'repository';
-    const dir = segments.slice(skillRootIndex + 2, -1).join('/') || 'root';
-    return { directory: dir, scope };
-  }
-  return { directory: segments.slice(0, -1).join('/') || 'root', scope: 'repository' };
-}
-
-/**
- * Derives a fallback description from the first prose paragraph in a skill document.
- *
- * @param body Markdown body with frontmatter removed.
- *
- * @return The first non-heading paragraph, or an empty string when none exists.
- */
-function fallbackDescription(body) {
-  return (
-    body
-      .replace(/^\s*#.+\n/, '')
-      .split(/\n\s*\n/)
-      .map((paragraph) => paragraph.replace(/\s+/g, ' ').trim())
-      .find((paragraph) => paragraph && !paragraph.startsWith('#')) ?? ''
-  );
-}
-
-/**
- * Converts a directory or skill name into a title-style label.
- *
- * @param value Slug containing words separated by hyphens or underscores.
- *
- * @return A human-readable label with each word capitalized.
- */
-function humanize(value) {
-  return value.replace(/[-_]+/g, ' ').replace(/\b\p{L}/gu, (letter) => letter.toUpperCase());
-}
-
-/**
- * Builds a sorted index of repository skills and writes it as JSON.
- *
- * @param repoRoot Repository root whose `.agents` and `.codex` skill trees are scanned.
- * @param outputPath Destination file for the generated skill index.
- *
- * @return The indexed skills, including their parsed metadata and Markdown bodies.
- */
-export async function generateSkillsIndex(repoRoot, outputPath) {
-  const root = resolve(repoRoot);
-  const files = await findSkillFiles(root);
-  const skills = await Promise.all(
-    files.map(async (path) => {
-      const source = await readFile(path, 'utf8');
-      const { body, metadata, metadataIssue } = splitFrontmatter(source);
-      const location = skillLocation(root, path);
-      const dirName = location.directory.split('/').at(-1) ?? 'skill';
-      const name = typeof metadata.name === 'string' ? metadata.name.trim() : dirName;
-      const title = /^#\s+(.+?)\s*#*\s*$/m.exec(body)?.[1]?.trim() ?? humanize(name);
-      const description =
-        typeof metadata.description === 'string'
-          ? metadata.description.trim()
-          : fallbackDescription(body);
-      return {
-        body,
-        description,
-        directory: location.directory,
-        metadata,
-        ...(metadataIssue ? { metadataIssue } : {}),
-        name,
-        scope: location.scope,
-        sourcePath: relative(root, path).split(sep).join('/'),
-        title,
-      };
-    }),
-  );
-  skills.sort((first, second) =>
-    `${first.scope}/${first.directory}/${first.name}`.localeCompare(
-      `${second.scope}/${second.directory}/${second.name}`,
-    ),
-  );
-  await mkdir(dirname(outputPath), { recursive: true });
-  await writeFile(outputPath, `${JSON.stringify(skills, null, 2)}\n`);
-  return skills;
-}
-if (process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname)) {
-  const root = resolve(process.argv[2] ?? process.cwd());
-  const outputPath = resolve(
-    process.argv[3] ?? join(root, 'dist/cache/skills.generated.json'),
-  );
-  const skills = await generateSkillsIndex(root, outputPath);
-  console.log(`Indexed ${skills.length} skills from ${root}`);
-}

package/site/src/components/SkillsExplorer.tsx

@@ -1,236 +0,0 @@
-/**
- * site/src/components/SkillsExplorer.tsx
- */
-
-/*//////////////////////////////////////////////////
-IMPORTS
-//////////////////////////////////////////////////*/
-
-// API
-import { useMemo, useState } from 'react';
-
-/*//////////////////////////////////////////////////
-CONFIG
-//////////////////////////////////////////////////*/
-
-/**
- * Skill content and metadata prepared for display in the repository skills explorer.
- */
-export type SkillRecord = {
-  body: string;
-  description: string;
-  directory: string;
-  metadata: Record<string, unknown>;
-  metadataIssue?: string;
-  name: string;
-  scope: string;
-  sourcePath: string;
-  title: string;
-};
-
-/*//////////////////////////////////////////////////
-HELPERS
-//////////////////////////////////////////////////*/
-
-/**
- * Converts scalar metadata to readable text and structured metadata to JSON.
- *
- * @param value Metadata value parsed from a skill's YAML frontmatter.
- *
- * @return Text suitable for searching and displaying in the explorer.
- */
-function metadataValue(value: unknown) {
-  if (typeof value === 'string') return value;
-  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
-  return JSON.stringify(value);
-}
-
-/**
- * Formats a count with a simple English plural suffix.
- *
- * @param count Number of matching items.
- * @param singular Singular label for one item.
- *
- * @return The count followed by the singular or plural label.
- */
-function plural(count: number, singular: string) {
-  return `${count} ${singular}${count === 1 ? '' : 's'}`;
-}
-
-/*//////////////////////////////////////////////////
-COMPONENTS
-//////////////////////////////////////////////////*/
-
-/**
- * Lets readers filter, select, and inspect the repository's indexed skill files.
- *
- * @param props Skill records built from the repository's `SKILL.md` files.
- *
- * @return A filterable list and the selected skill's description and content.
- */
-export function SkillsExplorer({ skills }: { skills: SkillRecord[] }) {
-  const [query, setQuery] = useState('');
-  const [aPath, setActivePath] = useState(skills[0]?.sourcePath ?? '');
-  const filteredSkills = useMemo(() => {
-    const normQuery = query.trim().toLocaleLowerCase();
-    if (!normQuery) return skills;
-    return skills.filter((skill) =>
-      [
-        skill.name,
-        skill.title,
-        skill.description,
-        skill.directory,
-        skill.scope,
-        skill.sourcePath,
-        JSON.stringify(skill.metadata),
-        skill.body,
-      ]
-        .join('\n')
-        .toLocaleLowerCase()
-        .includes(normQuery),
-    );
-  }, [query, skills]);
-  const selectedSkill =
-    filteredSkills.find((skill) => skill.sourcePath === aPath) ?? filteredSkills[0] ?? null;
-  const groups = useMemo(() => {
-    const byScope = new Map<string, SkillRecord[]>();
-    for (const skill of filteredSkills) {
-      const entries = byScope.get(skill.scope) ?? [];
-      entries.push(skill);
-      byScope.set(skill.scope, entries);
-    }
-    return [...byScope.entries()];
-  }, [filteredSkills]);
-  const metadataEntries = selectedSkill
-    ? Object.entries(selectedSkill.metadata).filter(
-        ([key]) => !['name', 'description'].includes(key),
-      )
-    : [];
-  return (
-    <section aria-label="Repository skills" className="my-8">
-      <header className="mb-4 flex flex-wrap items-end justify-between gap-6">
-        <div>
-          <p className="mb-1 text-xs font-bold uppercase tracking-wider text-gray-10">
-            Repository inventory
-          </p>
-          <h2 className="m-0">Skills</h2>
-          <p className="mb-0 mt-1 text-gray-10">
-            Browse the workflows and guidance files included in this repository.
-          </p>
-        </div>
-        <div aria-live="polite" className="grid justify-items-end text-sm text-gray-10">
-          <strong className="text-2xl leading-none text-primary-11">{skills.length}</strong>
-          <span>{plural(skills.length, 'skill')} indexed</span>
-        </div>
-      </header>
-      {skills.length ? (
-        <div className="grid min-w-0 items-start gap-4 md:grid-cols-[minmax(16rem,0.8fr)_minmax(0,1.6fr)]">
-          <nav
-            aria-label="Available skills"
-            className="max-h-[78vh] min-w-0 overflow-auto rounded-xl border border-gray-6 bg-gray-1 p-3"
-          >
-            <div>
-              <label className="text-sm font-medium text-gray-11" htmlFor="skills-explorer-filter">
-                Filter skills
-              </label>
-              <input
-                className="mt-1 w-full rounded-md border border-gray-6 bg-gray-1 px-3 py-2 text-sm text-gray-12 shadow-sm outline-none placeholder:text-gray-9 focus-visible:ring-2 focus-visible:ring-primary-8"
-                id="skills-explorer-filter"
-                onChange={(event) => setQuery(event.currentTarget.value)}
-                placeholder="Name, topic, or text"
-                type="search"
-                value={query}
-              />
-            </div>
-            <p aria-live="polite" className="mb-4 mt-2 text-xs text-gray-10">
-              Showing {filteredSkills.length} of {skills.length}
-            </p>
-            {groups.length ? (
-              groups.map(([scope, entries]) => (
-                <section aria-label={scope} className="mt-4 first:mt-0" key={scope}>
-                  <h3 className="mb-2 break-words text-xs font-bold uppercase text-gray-10">
-                    {scope}
-                  </h3>
-                  <ul className="m-0 grid list-none gap-1 p-0">
-                    {entries.map((skill) => (
-                      <li key={skill.sourcePath}>
-                        <button
-                          aria-pressed={selectedSkill?.sourcePath === skill.sourcePath}
-                          className={`grid h-auto w-full min-w-0 justify-start rounded-md border px-3 py-2 text-left transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-8 ${
-                            selectedSkill?.sourcePath === skill.sourcePath
-                              ? 'border-primary-7 bg-primary-3 text-primary-12'
-                              : 'border-transparent bg-transparent text-gray-11 hover:border-gray-6 hover:bg-gray-2 hover:text-gray-12'
-                          }`}
-                          onClick={() => setActivePath(skill.sourcePath)}
-                          type="button"
-                        >
-                          <span className="grid min-w-0 gap-1">
-                            <span className="font-semibold leading-snug">{skill.title}</span>
-                            <span className="line-clamp-2 text-xs font-normal text-gray-10">
-                              {skill.description || skill.name}
-                            </span>
-                            <span className="truncate text-[0.7rem] font-normal text-gray-9">
-                              {skill.directory}
-                            </span>
-                          </span>
-                        </button>
-                      </li>
-                    ))}
-                  </ul>
-                </section>
-              ))
-            ) : (
-              <p className="text-sm text-gray-10">No skills match “{query}”.</p>
-            )}
-          </nav>
-          {selectedSkill ? (
-            <article
-              aria-live="polite"
-              className="min-w-0 overflow-hidden rounded-xl border border-gray-6 bg-gray-1"
-            >
-              <header className="border-b border-gray-6 p-4">
-                <p className="mb-1 text-xs font-bold uppercase tracking-wider text-primary-11">
-                  {selectedSkill.scope}
-                </p>
-                <h3 className="mb-2 mt-0">{selectedSkill.title}</h3>
-                <p className="mb-2 text-gray-10">{selectedSkill.description}</p>
-                <p className="mb-0 break-all font-mono text-xs text-gray-9">
-                  {selectedSkill.sourcePath}
-                </p>
-              </header>
-              {metadataEntries.length ? (
-                <dl className="m-0 grid gap-3 border-b border-gray-6 p-4 sm:grid-cols-2">
-                  {metadataEntries.map(([key, value]) => (
-                    <div className="min-w-0" key={key}>
-                      <dt className="text-xs font-semibold uppercase text-gray-10">
-                        {key.replace(/[-_]+/g, ' ')}
-                      </dt>
-                      <dd className="mb-0 mt-1 break-words text-sm">{metadataValue(value)}</dd>
-                    </div>
-                  ))}
-                </dl>
-              ) : null}
-              {selectedSkill.metadataIssue ? (
-                <p className="m-4 rounded-md border border-gray-6 bg-gray-2 p-3 text-sm">
-                  Frontmatter could not be parsed: {selectedSkill.metadataIssue}
-                </p>
-              ) : null}
-              <details className="p-4" open>
-                <summary className="cursor-pointer font-semibold">Full skill instructions</summary>
-                <pre className="mt-3 max-h-[60vh] overflow-auto whitespace-pre-wrap break-words rounded-lg bg-gray-2 p-4 text-sm">
-                  <code>{selectedSkill.body}</code>
-                </pre>
-              </details>
-            </article>
-          ) : null}
-        </div>
-      ) : (
-        <p className="rounded-lg border border-gray-6 bg-gray-1 p-4 text-sm text-gray-10">
-          No SKILL.md files were found in this repository. Add skills under a .agents/skills or
-          .codex/skills folder, then rebuild the Docs site.
-        </p>
-      )}
-    </section>
-  );
-}
-export default SkillsExplorer;