handbook-building
Streamline Turbo application development with advanced script handling, JavaScript bundling, caching strategies, and element persistence across page loads. Enhance performance and maintain consistency in your projects.
Instructions
Building Turbo applications - covers script handling, JavaScript bundling, caching strategies, installing behavior with Stimulus, making transformations idempotent, and persisting elements across page loads
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- src/config.ts:50-55 (registration)Configuration entry defining the 'handbook-building' tool: name, description, source folder, and file.{ folder: 'handbook', file: '07_building.md', name: 'handbook-building', description: 'Building Turbo applications - covers script handling, JavaScript bundling, caching strategies, installing behavior with Stimulus, making transformations idempotent, and persisting elements across page loads' },
- src/index.ts:17-45 (registration)Dynamic registration loop that creates and registers the 'handbook-building' tool (and others) using server.tool with metadata from config and inline handler.docFiles.forEach(({ folder, file, name, description }) => { server.tool( name, description, async () => { try { const content = await readMarkdownFile(path.join(folder, file)); return { content: [ { type: "text", text: content } ] }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); return { content: [ { type: "text", text: `Error reading ${file}: ${errorMessage}` } ] }; } } ); });
- src/index.ts:21-43 (handler)Inline handler function for the tool: calls readMarkdownFile with the configured path, returns markdown as text content block or error message.async () => { try { const content = await readMarkdownFile(path.join(folder, file)); return { content: [ { type: "text", text: content } ] }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); return { content: [ { type: "text", text: `Error reading ${file}: ${errorMessage}` } ] }; } }
- src/documentReader.ts:14-61 (helper)Core helper function readMarkdownFile: intelligently fetches the markdown content from cache, GitHub raw, or local fallback with security checks.export async function readMarkdownFile(filename: string): Promise<string> { const filePath = path.join(docsFolder, filename); if (!filePath.startsWith(docsFolder)) { throw new Error("Invalid file path"); } // Get current commit info if we don't have it yet if (!mainBranchInfo) { try { const commitInfo = await fetchMainBranchInformation(); const cacheKey = `${commitInfo.sha.substring(0, 7)}-${commitInfo.timestamp}`; mainBranchInfo = { ...commitInfo, cacheKey }; } catch (shaError) { console.error('Failed to get GitHub commit info, falling back to direct fetch'); } } // Try to read from cache first if we have commit info if (mainBranchInfo) { const cachedFilePath = path.join(cacheFolder, mainBranchInfo.cacheKey, filename); try { const content = await fs.promises.readFile(cachedFilePath, "utf-8"); console.error(`Using cached content for ${mainBranchInfo.cacheKey}: ${filename}`); return content; } catch (cacheError) { // Cache miss, continue to fetch from GitHub } } // Fetch from GitHub try { return await fetchFromGitHub(filename, mainBranchInfo?.cacheKey); } catch (githubError) { console.error(`GitHub fetch failed: ${githubError}, attempting to read from local files...`); // Fallback: read from local files try { return await fs.promises.readFile(filePath, "utf-8"); } catch (localError) { const githubErrorMessage = githubError instanceof Error ? githubError.message : String(githubError); const localErrorMessage = localError instanceof Error ? localError.message : String(localError); throw new Error(`Failed to read file from GitHub (${githubErrorMessage}) and locally (${localErrorMessage})`); } } }