@ulysses-ai/create-workspace 0.13.0-beta.0

package/template/.claude/skills/build-docs-site/scripts/leak-grep.mjs

@@ -0,0 +1,328 @@
+#!/usr/bin/env node
+/**
+ * leak-grep.mjs — implementation-detail leak detector for the build-docs-site skill.
+ *
+ * Scans a project's dependency manifests to derive a list of installed
+ * package names, then greps documentation content for any mention of
+ * those names. The list is project-accurate — no hardcoded master list.
+ *
+ * Manifests scanned:
+ *   - package.json (Node)
+ *   - pyproject.toml (Python)
+ *   - requirements.txt (Python)
+ *   - Cargo.toml (Rust)
+ *   - Gemfile (Ruby)
+ *   - go.mod (Go)
+ *
+ * Excludes Tech Stack appendix files (where implementation choices are
+ * the subject) by file path filter.
+ *
+ * Usage:
+ *   node leak-grep.mjs <project-root> <docs-path> [--exclude path1,path2]
+ *
+ * Output: JSON to stdout
+ *   {
+ *     manifestsScanned: [...],
+ *     packagesFound: [...],
+ *     hits: [{file, line, term, context}],
+ *     excluded: [...]
+ *   }
+ */
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, basename } from 'node:path';
+
+// ---------- CLI parsing ----------
+
+const args = process.argv.slice(2);
+if (args.length < 2) {
+  console.error('Usage: leak-grep.mjs <project-root> <docs-path> [--exclude path1,path2]');
+  process.exit(1);
+}
+
+const projectRoot = args[0];
+const docsPath = args[1];
+const excludeFlag = args.indexOf('--exclude');
+const userExcludes = excludeFlag >= 0 && args[excludeFlag + 1]
+  ? args[excludeFlag + 1].split(',')
+  : [];
+
+// Default excludes — the Tech Stack appendix is where implementation
+// details are the subject. Match common naming conventions.
+const defaultExcludes = [
+  'tech-stack',
+  'appendix-tech-stack',
+  'appendix/tech-stack',
+  'technology',
+  'stack',
+];
+const excludes = [...defaultExcludes, ...userExcludes];
+
+// ---------- Manifest scanning ----------
+
+const packageNames = new Set();
+const manifestsScanned = [];
+
+function scanManifests(dir) {
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry);
+    let stat;
+    try {
+      stat = statSync(full);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) {
+      // Skip common ignored directories
+      if (['node_modules', '.git', 'dist', 'build', '.next', '.venv', 'venv', '__pycache__'].includes(entry)) {
+        continue;
+      }
+      scanManifests(full);
+    } else {
+      const name = basename(full);
+      if (['package.json', 'pyproject.toml', 'requirements.txt', 'Cargo.toml', 'Gemfile', 'go.mod'].includes(name)) {
+        const extracted = extractPackages(name, full);
+        if (extracted.length > 0) {
+          manifestsScanned.push(relative(projectRoot, full));
+          extracted.forEach((p) => packageNames.add(p));
+        }
+      }
+    }
+  }
+}
+
+function extractPackages(manifestName, fullPath) {
+  let content;
+  try {
+    content = readFileSync(fullPath, 'utf8');
+  } catch {
+    return [];
+  }
+
+  switch (manifestName) {
+    case 'package.json':
+      return extractFromPackageJson(content);
+    case 'pyproject.toml':
+      return extractFromPyprojectToml(content);
+    case 'requirements.txt':
+      return extractFromRequirementsTxt(content);
+    case 'Cargo.toml':
+      return extractFromCargoToml(content);
+    case 'Gemfile':
+      return extractFromGemfile(content);
+    case 'go.mod':
+      return extractFromGoMod(content);
+    default:
+      return [];
+  }
+}
+
+function extractFromPackageJson(content) {
+  try {
+    const parsed = JSON.parse(content);
+    const all = {
+      ...parsed.dependencies,
+      ...parsed.devDependencies,
+      ...parsed.peerDependencies,
+      ...parsed.optionalDependencies,
+    };
+    return Object.keys(all).map((name) => {
+      // Strip scope: @scope/name → name (also keep both for matching)
+      const stripped = name.startsWith('@') ? name.split('/')[1] || name : name;
+      return stripped;
+    });
+  } catch {
+    return [];
+  }
+}
+
+function extractFromPyprojectToml(content) {
+  // Naive TOML parsing — look for dependency lines like:
+  //   name = "..."  or  "package-name>=1.0"  or  package-name = "1.0"
+  const names = new Set();
+  const lines = content.split('\n');
+  let inDeps = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('[')) {
+      inDeps = /\[(tool\.poetry\.|project\.|tool\.pdm\.)?(dev-)?dependencies\]/.test(trimmed);
+      continue;
+    }
+    if (inDeps) {
+      // poetry style: name = "1.0" or {version = "..."}
+      const poetryMatch = trimmed.match(/^([a-zA-Z0-9][a-zA-Z0-9_-]*)\s*=/);
+      if (poetryMatch) names.add(poetryMatch[1]);
+      // pep621 style in dependencies array: "name>=1.0",
+      const pep621Match = trimmed.match(/^["']([a-zA-Z0-9][a-zA-Z0-9_-]*)/);
+      if (pep621Match) names.add(pep621Match[1]);
+    }
+  }
+  return [...names];
+}
+
+function extractFromRequirementsTxt(content) {
+  const names = [];
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const match = trimmed.match(/^([a-zA-Z0-9][a-zA-Z0-9_-]*)/);
+    if (match) names.push(match[1]);
+  }
+  return names;
+}
+
+function extractFromCargoToml(content) {
+  const names = new Set();
+  const lines = content.split('\n');
+  let inDeps = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('[')) {
+      inDeps = /\[(dev-|build-)?dependencies\]/.test(trimmed);
+      continue;
+    }
+    if (inDeps) {
+      const match = trimmed.match(/^([a-zA-Z0-9][a-zA-Z0-9_-]*)\s*=/);
+      if (match) names.add(match[1]);
+    }
+  }
+  return [...names];
+}
+
+function extractFromGemfile(content) {
+  const names = [];
+  for (const line of content.split('\n')) {
+    const match = line.match(/^\s*gem\s+["']([a-zA-Z0-9][a-zA-Z0-9_-]*)["']/);
+    if (match) names.push(match[1]);
+  }
+  return names;
+}
+
+function extractFromGoMod(content) {
+  const names = new Set();
+  const lines = content.split('\n');
+  let inRequire = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith('require (')) {
+      inRequire = true;
+      continue;
+    }
+    if (inRequire && trimmed === ')') {
+      inRequire = false;
+      continue;
+    }
+    const lineToCheck = trimmed.startsWith('require ') ? trimmed.replace(/^require\s+/, '') : (inRequire ? trimmed : null);
+    if (lineToCheck) {
+      // last path segment as the package "name"
+      const match = lineToCheck.match(/^[a-zA-Z0-9./_-]+/);
+      if (match) {
+        const segments = match[0].split('/');
+        const last = segments[segments.length - 1];
+        if (last) names.add(last);
+      }
+    }
+  }
+  return [...names];
+}
+
+// ---------- Doc walking and grepping ----------
+
+const hits = [];
+const excludedFiles = [];
+
+function isExcluded(filePath) {
+  const rel = relative(docsPath, filePath).replace(/\\/g, '/');
+  return excludes.some((e) => rel.includes(e));
+}
+
+function walkDocs(dir) {
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry);
+    let stat;
+    try {
+      stat = statSync(full);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) {
+      walkDocs(full);
+    } else if (/\.(md|mdx)$/.test(entry)) {
+      if (isExcluded(full)) {
+        excludedFiles.push(relative(projectRoot, full));
+        continue;
+      }
+      grepFile(full);
+    }
+  }
+}
+
+function grepFile(filePath) {
+  let content;
+  try {
+    content = readFileSync(filePath, 'utf8');
+  } catch {
+    return;
+  }
+  const lines = content.split('\n');
+  const relPath = relative(projectRoot, filePath);
+
+  let inCodeBlock = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim().startsWith('```')) {
+      inCodeBlock = !inCodeBlock;
+      continue;
+    }
+    if (inCodeBlock) continue; // Don't flag terms in code blocks
+
+    for (const pkg of packageNames) {
+      // Word boundary match, case-sensitive
+      // Skip very short package names (< 3 chars) to reduce noise
+      if (pkg.length < 3) continue;
+      const escaped = pkg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const regex = new RegExp(`\\b${escaped}\\b`);
+      if (regex.test(line)) {
+        hits.push({
+          file: relPath,
+          line: i + 1,
+          term: pkg,
+          context: line.trim().slice(0, 200),
+        });
+      }
+    }
+  }
+}
+
+// ---------- Run ----------
+
+scanManifests(projectRoot);
+walkDocs(docsPath);
+
+const result = {
+  manifestsScanned,
+  packagesFound: [...packageNames].sort(),
+  excluded: excludedFiles,
+  hits,
+  summary: {
+    manifestCount: manifestsScanned.length,
+    packageCount: packageNames.size,
+    excludedFileCount: excludedFiles.length,
+    hitCount: hits.length,
+  },
+};
+
+console.log(JSON.stringify(result, null, 2));
+process.exit(hits.length > 0 ? 1 : 0);

package/template/.claude/skills/build-docs-site/templates/custom.css.tmpl

@@ -0,0 +1,212 @@
+/**
+ * Documentation site custom CSS.
+ *
+ * This file is a template — the build-docs-site skill fills in the
+ * brand placeholders (marked with {{...}}) with values from the
+ * Phase 1 brand identity question. After substitution the file is a
+ * valid Docusaurus custom.css.
+ *
+ * Sections:
+ *   1. Brand fonts (imports)
+ *   2. Infima theme overrides (light)
+ *   3. Infima theme overrides (dark)
+ *   4. Diagram tokens (--dx-*)
+ *   5. Diagram class layer (.dx-fill-* / .dx-stroke-*)
+ *   6. Diagram container styling
+ *   7. Typography polish (justified body, heading spacing, column width)
+ */
+
+/* ============================================================
+ * 1. Brand fonts
+ * Replace with @import or @font-face declarations for your fonts.
+ * Example: @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap');
+ * ============================================================ */
+{{BRAND_FONTS_IMPORT}}
+
+/* ============================================================
+ * 2. Infima theme overrides (light mode)
+ * ============================================================ */
+:root {
+  --ifm-color-primary: {{BRAND_PRIMARY}};
+  --ifm-color-primary-dark: {{BRAND_PRIMARY_DARK}};
+  --ifm-color-primary-darker: {{BRAND_PRIMARY_DARKER}};
+  --ifm-color-primary-darkest: {{BRAND_PRIMARY_DARKEST}};
+  --ifm-color-primary-light: {{BRAND_PRIMARY_LIGHT}};
+  --ifm-color-primary-lighter: {{BRAND_PRIMARY_LIGHTER}};
+  --ifm-color-primary-lightest: {{BRAND_PRIMARY_LIGHTEST}};
+
+  --ifm-background-color: {{BRAND_BACKGROUND}};
+  --ifm-font-color-base: {{BRAND_TEXT}};
+
+  --ifm-font-family-base: {{BRAND_FONT_BODY}}, system-ui, -apple-system, sans-serif;
+  --ifm-heading-font-family: {{BRAND_FONT_HEADING}}, system-ui, -apple-system, sans-serif;
+  --ifm-font-family-monospace: {{BRAND_FONT_MONO}}, 'SF Mono', Consolas, monospace;
+
+  --ifm-code-font-size: 90%;
+  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
+}
+
+/* ============================================================
+ * 3. Infima theme overrides (dark mode)
+ * ============================================================ */
+[data-theme='dark'] {
+  --ifm-color-primary: {{BRAND_PRIMARY_DARK_MODE}};
+  --ifm-color-primary-dark: {{BRAND_PRIMARY_DARK_MODE_DARK}};
+  --ifm-color-primary-darker: {{BRAND_PRIMARY_DARK_MODE_DARKER}};
+  --ifm-color-primary-darkest: {{BRAND_PRIMARY_DARK_MODE_DARKEST}};
+  --ifm-color-primary-light: {{BRAND_PRIMARY_DARK_MODE_LIGHT}};
+  --ifm-color-primary-lighter: {{BRAND_PRIMARY_DARK_MODE_LIGHTER}};
+  --ifm-color-primary-lightest: {{BRAND_PRIMARY_DARK_MODE_LIGHTEST}};
+
+  --ifm-background-color: {{BRAND_BACKGROUND_DARK}};
+  --ifm-font-color-base: {{BRAND_TEXT_DARK}};
+
+  --docusaurus-highlighted-code-line-bg: rgba(255, 255, 255, 0.1);
+}
+
+/* ============================================================
+ * 4. Diagram tokens (--dx-*)
+ *
+ * Semantic colors used by the diagram primitives library.
+ * The class layer below resolves these for fill/stroke.
+ * Keep in sync with primitives/tokens.ts hex values.
+ * ============================================================ */
+:root {
+  --dx-primary: {{BRAND_PRIMARY}};
+  --dx-accent: {{BRAND_ACCENT}};
+  --dx-surface: #FFFFFF;
+  --dx-surface-strong: #F2F2F2;
+  --dx-text: #1A1A1A;
+  --dx-text-muted: #666666;
+  --dx-stroke: #CCCCCC;
+  --dx-stroke-strong: #888888;
+  --dx-diagram-bg: {{BRAND_BACKGROUND}};
+}
+
+[data-theme='dark'] {
+  --dx-primary: {{BRAND_PRIMARY_DARK_MODE}};
+  --dx-accent: {{BRAND_ACCENT_DARK_MODE}};
+  --dx-surface: #1A1A1A;
+  --dx-surface-strong: #2A2A2A;
+  --dx-text: #EDEDED;
+  --dx-text-muted: #999999;
+  --dx-stroke: #444444;
+  --dx-stroke-strong: #777777;
+  --dx-diagram-bg: {{BRAND_BACKGROUND_DARK}};
+}
+
+/* ============================================================
+ * 5. Diagram class layer
+ *
+ * CSS variables in `fill="var(--x)"` or inline style do not paint
+ * reliably in Chromium's SVG pipeline. The variables resolve correctly
+ * through class selectors. Apply via className on SVG elements:
+ *
+ *   <rect className="dx-fill-primary dx-stroke-stroke" />
+ * ============================================================ */
+.dx-fill-primary { fill: var(--dx-primary); }
+.dx-fill-accent { fill: var(--dx-accent); }
+.dx-fill-surface { fill: var(--dx-surface); }
+.dx-fill-surface-strong { fill: var(--dx-surface-strong); }
+.dx-fill-text { fill: var(--dx-text); }
+.dx-fill-text-muted { fill: var(--dx-text-muted); }
+.dx-fill-stroke { fill: var(--dx-stroke); }
+.dx-fill-stroke-strong { fill: var(--dx-stroke-strong); }
+
+.dx-stroke-primary { stroke: var(--dx-primary); }
+.dx-stroke-accent { stroke: var(--dx-accent); }
+.dx-stroke-surface { stroke: var(--dx-surface); }
+.dx-stroke-surface-strong { stroke: var(--dx-surface-strong); }
+.dx-stroke-text { stroke: var(--dx-text); }
+.dx-stroke-text-muted { stroke: var(--dx-text-muted); }
+.dx-stroke-stroke { stroke: var(--dx-stroke); }
+.dx-stroke-stroke-strong { stroke: var(--dx-stroke-strong); }
+
+/* ============================================================
+ * 6. Diagram container styling
+ * ============================================================ */
+.dx-diagram-container {
+  background: var(--dx-diagram-bg);
+  border-radius: 8px;
+  padding: 24px;
+  margin: 2rem 0;
+  border: 1px solid var(--dx-stroke);
+}
+
+.dx-diagram-container svg {
+  width: 100%;
+  height: auto;
+  display: block;
+}
+
+.dx-diagram-caption {
+  margin-top: 1rem;
+  font-size: 0.875rem;
+  color: var(--dx-text-muted);
+  text-align: center;
+  font-style: italic;
+}
+
+/* ============================================================
+ * 7. Typography polish
+ *
+ * Captured defaults that produce comfortable long-form reading.
+ * The chapter-length question in Phase 1 may inform whether you
+ * adjust these — these are the Linear/Together defaults.
+ * ============================================================ */
+
+/* Justified body text with hyphenation */
+.markdown p,
+.markdown li {
+  text-align: justify;
+  hyphens: auto;
+  -webkit-hyphens: auto;
+  -ms-hyphens: auto;
+}
+
+/* Heading spacing — generous top, controlled bottom */
+.markdown h2 {
+  margin-top: 3.5rem;
+  margin-bottom: 1.25rem;
+}
+
+.markdown h3 {
+  margin-top: 2.5rem;
+  margin-bottom: 1rem;
+}
+
+.markdown h4 {
+  margin-top: 2rem;
+  margin-bottom: 0.75rem;
+}
+
+/* Collapse spacing between adjacent headings (avoid double-stacking) */
+.markdown h2 + h3,
+.markdown h3 + h4 {
+  margin-top: 1rem;
+}
+
+/* Paragraph and list-item bottom spacing */
+.markdown p {
+  margin-bottom: 1.25rem;
+}
+
+.markdown li {
+  margin-bottom: 0.4rem;
+}
+
+.markdown li:last-child {
+  margin-bottom: 1.25rem;
+}
+
+/* Content column width — wide enough for justified text to look even */
+.markdown {
+  max-width: 760px;
+}
+
+/* Code blocks should not be justified */
+.markdown pre,
+.markdown pre code {
+  text-align: left;
+  hyphens: none;
+}

package/template/.claude/skills/build-docs-site/templates/docusaurus.config.ts.tmpl

@@ -0,0 +1,95 @@
+import { themes as prismThemes } from 'prism-react-renderer';
+import type { Config } from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+/**
+ * Docusaurus configuration for the documentation site.
+ * Generated by the build-docs-site skill from a template.
+ *
+ * Placeholders to substitute:
+ *   {{SITE_TITLE}}        — the site's display title
+ *   {{SITE_TAGLINE}}      — short tagline shown in the navbar/footer
+ *   {{SITE_URL}}          — production URL (e.g., https://docs.example.com)
+ *   {{SITE_BASE_URL}}     — base path (usually '/')
+ *   {{ORG_NAME}}          — GitHub org or owner
+ *   {{REPO_NAME}}         — GitHub repo name (for edit links)
+ *   {{FAVICON_PATH}}      — path to favicon under static/
+ *   {{COPYRIGHT_OWNER}}   — name shown in the footer copyright
+ */
+
+const config: Config = {
+  title: '{{SITE_TITLE}}',
+  tagline: '{{SITE_TAGLINE}}',
+  favicon: '{{FAVICON_PATH}}',
+
+  url: '{{SITE_URL}}',
+  baseUrl: '{{SITE_BASE_URL}}',
+
+  organizationName: '{{ORG_NAME}}',
+  projectName: '{{REPO_NAME}}',
+
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'warn',
+
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          // Docs at the site root — no /docs/ prefix
+          routeBasePath: '/',
+          sidebarPath: './sidebars.ts',
+          editUrl: 'https://github.com/{{ORG_NAME}}/{{REPO_NAME}}/tree/main/',
+        },
+        // Blog disabled — this is a docs-only site
+        blog: false,
+        theme: {
+          customCss: './src/css/custom.css',
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  themeConfig: {
+    colorMode: {
+      defaultMode: 'light',
+      disableSwitch: false,
+      respectPrefersColorScheme: true,
+    },
+    docs: {
+      sidebar: {
+        hideable: true,
+        autoCollapseCategories: true,
+      },
+    },
+    navbar: {
+      title: '{{SITE_TITLE}}',
+      logo: {
+        alt: '{{SITE_TITLE}} Logo',
+        src: '{{FAVICON_PATH}}',
+      },
+      items: [
+        {
+          href: 'https://github.com/{{ORG_NAME}}/{{REPO_NAME}}',
+          label: 'GitHub',
+          position: 'right',
+        },
+      ],
+    },
+    footer: {
+      style: 'dark',
+      copyright: `Copyright © ${new Date().getFullYear()} {{COPYRIGHT_OWNER}}.`,
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+    },
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;