@terra-symposium/docs 0.1.75 → 0.1.76

package/bin/generate-skills.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { parse } from 'yaml';
+
+const ignoredDirectories = new Set([
+  '.astro',
+  '.cache',
+  '.git',
+  '.next',
+  '.nuxt',
+  '.output',
+  '.svelte-kit',
+  '.turbo',
+  '.vite',
+  '.vercel',
+  '.wrangler',
+  'build',
+  'coverage',
+  'dist',
+  'docs-dist',
+  'lib-dist',
+  'node_modules',
+  'site-dist',
+  'target',
+  'vendor',
+]);
+
+async function findSkillFiles(directory, files = []) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory() && ignoredDirectories.has(entry.name)) continue;
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) await findSkillFiles(path, files);
+    else if (entry.isFile() && entry.name === 'SKILL.md') files.push(path);
+  }
+  return files;
+}
+
+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 (error) {
+    return {
+      body: source.slice(match[0].length).trim(),
+      metadata: {},
+      metadataIssue: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function skillLocation(root, path) {
+  const segments = relative(root, path).split(sep);
+  const skillRootIndex = segments.findIndex(
+    (segment, index) =>
+      (segment === '.agents' || segment === '.codex') && segments[index + 1] === 'skills',
+  );
+  if (skillRootIndex >= 0) {
+    const scope = segments.slice(0, skillRootIndex).join('/') || 'repository';
+    const directory = segments.slice(skillRootIndex + 2, -1).join('/') || 'root';
+    return { directory, scope };
+  }
+  return {
+    directory: segments.slice(0, -1).join('/') || 'root',
+    scope: 'repository',
+  };
+}
+
+function fallbackDescription(body) {
+  return (
+    body
+      .replace(/^\s*#.+\n/, '')
+      .split(/\n\s*\n/)
+      .map((paragraph) => paragraph.replace(/\s+/g, ' ').trim())
+      .find((paragraph) => paragraph && !paragraph.startsWith('#')) ?? ''
+  );
+}
+
+function humanize(value) {
+  return value.replace(/[-_]+/g, ' ').replace(/\b\p{L}/gu, (letter) => letter.toUpperCase());
+}
+
+export async function generateSkillsIndex(repositoryRoot, outputPath) {
+  const root = resolve(repositoryRoot);
+  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 directoryName = location.directory.split('/').at(-1) ?? 'skill';
+      const name = typeof metadata.name === 'string' ? metadata.name.trim() : directoryName;
+      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, '.terra-docs/cache/skills.generated.json'));
+  const skills = await generateSkillsIndex(root, outputPath);
+  console.log(`Indexed ${skills.length} skills from ${root}`);
+}

package/bin/terra-docs.mjs

@@ -6,6 +6,7 @@ import { dirname, extname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
 import { parse } from 'yaml';
+import { generateSkillsIndex } from './generate-skills.mjs';
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const require = createRequire(import.meta.url);
@@ -45,6 +46,7 @@ const publicRoot = resolve(root, '.terra-docs/public');
 const publicAssetsRoot = resolve(publicRoot, '_terra-docs/assets');
 const outputDirectory = options.get('--out') ?? 'dist/docs';
 const searchIndexPath = resolve(publicRoot, '_terra-docs/search-index.json');
+const skillsIndexPath = resolve(root, '.terra-docs/cache/skills.generated.json');
 const excludedDirectories = new Set(['node_modules', '.astro', 'dist']);
 const manifest = await readJson(resolve(root, 'package.json')).catch(() => ({}));
 const siteTitle = options.get('--title') ?? titleFromName(manifest.name) ?? 'Documentation';
@@ -183,7 +185,10 @@ const env = {
   PUBLIC_TERRA_DOCS_DESCRIPTION: siteDescription,
 };
 
-if (mode !== 'preview') await buildSearchIndex();
+if (mode !== 'preview') {
+  await generateSkillsIndex(root, skillsIndexPath);
+  await buildSearchIndex();
+}
 
 function runAstro(command) {
   const args = [astroCli, command, '--root', root, '--config', relative(root, configFile)];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terra-symposium/docs",
-  "version": "0.1.75",
+  "version": "0.1.76",
   "description": "Terra Docs workspace and Markdown site generator.",
   "repository": {
     "type": "git",
@@ -35,7 +35,11 @@
       "import": "./lib-dist/components/LocalDocsWorkspace.js"
     },
     "./site-layout.astro": "./src/components/SiteLayout.astro",
-    "./not-found.astro": "./src/components/NotFound.astro"
+    "./not-found.astro": "./src/components/NotFound.astro",
+    "./skills": {
+      "types": "./site/src/components/SkillsExplorer.tsx",
+      "import": "./site/src/components/SkillsExplorer.tsx"
+    }
   },
   "bin": {
     "terra-docs": "bin/terra-docs.mjs"

package/site/src/components/SkillsExplorer.tsx

@@ -0,0 +1,157 @@
+import { useMemo, useState } from 'react';
+import '../styles/skills-explorer.css';
+
+export type SkillRecord = {
+  body: string;
+  description: string;
+  directory: string;
+  metadata: Record<string, unknown>;
+  metadataIssue?: string;
+  name: string;
+  scope: string;
+  sourcePath: string;
+  title: string;
+};
+
+function metadataValue(value: unknown) {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  return JSON.stringify(value);
+}
+
+function plural(count: number, singular: string) {
+  return `${count} ${singular}${count === 1 ? '' : 's'}`;
+}
+
+export function SkillsExplorer({ skills }: { skills: SkillRecord[] }) {
+  const [query, setQuery] = useState('');
+  const [activePath, setActivePath] = useState(skills[0]?.sourcePath ?? '');
+  const filteredSkills = useMemo(() => {
+    const normalizedQuery = query.trim().toLocaleLowerCase();
+    if (!normalizedQuery) 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(normalizedQuery),
+    );
+  }, [query, skills]);
+  const selectedSkill =
+    filteredSkills.find((skill) => skill.sourcePath === activePath) ?? 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="docs-skills">
+      <header className="docs-skills__header">
+        <div>
+          <p className="docs-skills__eyebrow">Repository inventory</p>
+          <h2>Skills</h2>
+          <p>Browse the workflows and guidance files included in this repository.</p>
+        </div>
+        <div aria-live="polite" className="docs-skills__summary">
+          <strong>{skills.length}</strong>
+          <span>{plural(skills.length, 'skill')} indexed</span>
+        </div>
+      </header>
+
+      {skills.length ? (
+        <div className="docs-skills__layout">
+          <nav aria-label="Available skills" className="docs-skills__index">
+            <label className="docs-skills__filter">
+              <span>Filter skills</span>
+              <input
+                onChange={(event) => setQuery(event.currentTarget.value)}
+                placeholder="Name, topic, or text"
+                type="search"
+                value={query}
+              />
+            </label>
+            <p aria-live="polite" className="docs-skills__count">
+              Showing {filteredSkills.length} of {skills.length}
+            </p>
+            {groups.length ? (
+              groups.map(([scope, entries]) => (
+                <section aria-label={scope} className="docs-skills__group" key={scope}>
+                  <h3>{scope}</h3>
+                  <ul>
+                    {entries.map((skill) => (
+                      <li key={skill.sourcePath}>
+                        <button
+                          aria-current={selectedSkill?.sourcePath === skill.sourcePath ? 'true' : undefined}
+                          className="docs-skills__item"
+                          onClick={() => setActivePath(skill.sourcePath)}
+                          type="button"
+                        >
+                          <span className="docs-skills__item-title">{skill.title}</span>
+                          <span className="docs-skills__item-description">{skill.description || skill.name}</span>
+                          <span className="docs-skills__item-path">{skill.directory}</span>
+                        </button>
+                      </li>
+                    ))}
+                  </ul>
+                </section>
+              ))
+            ) : (
+              <p className="docs-skills__empty">No skills match “{query}”.</p>
+            )}
+          </nav>
+
+          {selectedSkill ? (
+            <article aria-live="polite" className="docs-skills__detail">
+              <header>
+                <p className="docs-skills__eyebrow">{selectedSkill.scope}</p>
+                <h3>{selectedSkill.title}</h3>
+                <p className="docs-skills__description">{selectedSkill.description}</p>
+                <p className="docs-skills__source-path">{selectedSkill.sourcePath}</p>
+              </header>
+              {metadataEntries.length ? (
+                <dl className="docs-skills__metadata">
+                  {metadataEntries.map(([key, value]) => (
+                    <div key={key}>
+                      <dt>{key.replace(/[-_]+/g, ' ')}</dt>
+                      <dd>{metadataValue(value)}</dd>
+                    </div>
+                  ))}
+                </dl>
+              ) : null}
+              {selectedSkill.metadataIssue ? (
+                <p className="docs-skills__metadata-issue">Frontmatter could not be parsed: {selectedSkill.metadataIssue}</p>
+              ) : null}
+              <details className="docs-skills__source" open>
+                <summary>Full skill instructions</summary>
+                <pre><code>{selectedSkill.body}</code></pre>
+              </details>
+            </article>
+          ) : null}
+        </div>
+      ) : (
+        <p className="docs-skills__empty">
+          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;

package/site/src/styles/skills-explorer.css

@@ -0,0 +1,268 @@
+.docs-skills {
+  margin-block: 2rem;
+}
+
+.docs-skills__header {
+  display: flex;
+  align-items: flex-end;
+  justify-content: space-between;
+  gap: 1.5rem;
+  margin-bottom: 1rem;
+}
+
+.docs-skills__header h2,
+.docs-skills__detail h3 {
+  margin: 0;
+}
+
+.docs-skills__header p:not(.docs-skills__eyebrow) {
+  margin: 0.4rem 0 0;
+  color: color-mix(in srgb, currentColor 72%, transparent);
+}
+
+.docs-skills__eyebrow {
+  margin: 0 0 0.35rem;
+  color: color-mix(in srgb, currentColor 64%, transparent);
+  font-size: 0.75rem;
+  font-weight: 700;
+  letter-spacing: 0.07em;
+  text-transform: uppercase;
+}
+
+.docs-skills__summary {
+  display: grid;
+  justify-items: end;
+  color: color-mix(in srgb, currentColor 70%, transparent);
+  font-size: 0.85rem;
+}
+
+.docs-skills__summary strong {
+  color: var(--docs-accent, currentColor);
+  font-size: 1.6rem;
+  line-height: 1;
+}
+
+.docs-skills__layout {
+  display: grid;
+  grid-template-columns: minmax(16rem, 0.8fr) minmax(0, 1.6fr);
+  align-items: start;
+  gap: 1rem;
+}
+
+.docs-skills__index,
+.docs-skills__detail {
+  min-width: 0;
+  overflow: hidden;
+  border: 1px solid color-mix(in srgb, currentColor 18%, transparent);
+  border-radius: 0.75rem;
+  background: color-mix(in srgb, currentColor 3%, transparent);
+}
+
+.docs-skills__index {
+  max-height: 78vh;
+  overflow: auto;
+  padding: 0.75rem;
+}
+
+.docs-skills__filter {
+  display: grid;
+  gap: 0.35rem;
+  font-size: 0.8rem;
+  font-weight: 600;
+}
+
+.docs-skills__filter input {
+  box-sizing: border-box;
+  width: 100%;
+  min-height: 2.5rem;
+  border: 1px solid color-mix(in srgb, currentColor 24%, transparent);
+  border-radius: 0.45rem;
+  background: var(--background, transparent);
+  color: inherit;
+  font: inherit;
+  font-weight: 400;
+  padding: 0.45rem 0.6rem;
+}
+
+.docs-skills__filter input:focus-visible,
+.docs-skills__item:focus-visible {
+  outline: 2px solid var(--docs-accent, currentColor);
+  outline-offset: 2px;
+}
+
+.docs-skills__count {
+  margin: 0.65rem 0 1rem;
+  color: color-mix(in srgb, currentColor 65%, transparent);
+  font-size: 0.8rem;
+}
+
+.docs-skills__group + .docs-skills__group {
+  margin-top: 1rem;
+}
+
+.docs-skills__group h3 {
+  margin: 0 0 0.4rem;
+  color: color-mix(in srgb, currentColor 68%, transparent);
+  font-size: 0.75rem;
+  font-weight: 700;
+  overflow-wrap: anywhere;
+  text-transform: uppercase;
+}
+
+.docs-skills__group ul {
+  display: grid;
+  gap: 0.35rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.docs-skills__item {
+  display: grid;
+  width: 100%;
+  min-width: 0;
+  gap: 0.2rem;
+  border: 0;
+  border-radius: 0.5rem;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+  font: inherit;
+  padding: 0.55rem;
+  text-align: left;
+}
+
+.docs-skills__item:hover,
+.docs-skills__item[aria-current='true'] {
+  background: color-mix(in srgb, var(--docs-accent, currentColor) 12%, transparent);
+}
+
+.docs-skills__item[aria-current='true'] .docs-skills__item-title {
+  color: var(--docs-accent, currentColor);
+  font-weight: 700;
+}
+
+.docs-skills__item-title {
+  font-weight: 600;
+}
+
+.docs-skills__item-description,
+.docs-skills__item-path {
+  color: color-mix(in srgb, currentColor 68%, transparent);
+  font-size: 0.78rem;
+  line-height: 1.4;
+}
+
+.docs-skills__item-path,
+.docs-skills__source-path {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  overflow-wrap: anywhere;
+}
+
+.docs-skills__detail > header {
+  padding: 1.25rem 1.25rem 0.75rem;
+}
+
+.docs-skills__description {
+  margin: 0.6rem 0;
+  color: color-mix(in srgb, currentColor 74%, transparent);
+}
+
+.docs-skills__source-path {
+  margin: 0;
+  color: color-mix(in srgb, currentColor 60%, transparent);
+  font-size: 0.75rem;
+}
+
+.docs-skills__metadata {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, 11rem), 1fr));
+  gap: 0.6rem;
+  margin: 0;
+  padding: 0.75rem 1.25rem 1.25rem;
+}
+
+.docs-skills__metadata > div {
+  min-width: 0;
+  border: 1px solid color-mix(in srgb, currentColor 15%, transparent);
+  border-radius: 0.5rem;
+  padding: 0.6rem 0.7rem;
+}
+
+.docs-skills__metadata dt {
+  color: color-mix(in srgb, currentColor 62%, transparent);
+  font-size: 0.72rem;
+  font-weight: 700;
+  text-transform: capitalize;
+}
+
+.docs-skills__metadata dd {
+  margin: 0.2rem 0 0;
+  font-size: 0.82rem;
+  overflow-wrap: anywhere;
+}
+
+.docs-skills__metadata-issue {
+  margin: 0 1.25rem 1rem;
+  color: #a12b2b;
+  font-size: 0.85rem;
+}
+
+.docs-skills__source {
+  border-top: 1px solid color-mix(in srgb, currentColor 16%, transparent);
+}
+
+.docs-skills__source summary {
+  cursor: pointer;
+  font-weight: 600;
+  padding: 0.8rem 1.25rem;
+}
+
+.docs-skills__source summary:focus-visible {
+  outline: 2px solid var(--docs-accent, currentColor);
+  outline-offset: -2px;
+}
+
+.docs-skills__source pre {
+  max-height: 60vh;
+  overflow: auto;
+  margin: 0;
+  border-top: 1px solid color-mix(in srgb, currentColor 12%, transparent);
+  background: color-mix(in srgb, currentColor 4%, transparent);
+  padding: 1rem 1.25rem;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 0.8rem;
+  line-height: 1.6;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+.docs-skills__empty {
+  border: 1px solid color-mix(in srgb, currentColor 18%, transparent);
+  border-radius: 0.75rem;
+  padding: 1rem;
+}
+
+@media (max-width: 48rem) {
+  .docs-skills__header {
+    align-items: flex-start;
+  }
+
+  .docs-skills__layout {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .docs-skills__index {
+    max-height: 45vh;
+  }
+}
+
+@media (max-width: 30rem) {
+  .docs-skills__header {
+    flex-direction: column;
+  }
+
+  .docs-skills__summary {
+    justify-items: start;
+  }
+}