wip

Author: pkosiec

investigation/investigation.md

@@ -48,7 +48,7 @@ All those limitations can be resolved by contributions to the plugin, post-proce
 1. Host `llms.txt` and MD files on our website (versioned docs)
    - Advantage: We can update the AI docs without releasing new versions of the packages
    - Downside: Agent needs to fetch the documentation from the website which are not as reliable as the local files
-2. Embed llms.txt and MD files into the packages
+2. Embed `llms.txt` and MD files into the packages
    1. Embed llms.txt and MD files into the packages - all docs files
    2. Split generation for appkit and appkit-ui
       1. Limitations: we'd need to contribute to the plugin to add support for:

packages/appkit-ui/package.json

@@ -11,6 +11,7 @@
     "dist",
     "bin",
     "scripts",
+    "docs",
     "CLAUDE.md",
     "AGENTS.md",
     "llms.txt",

packages/appkit/package.json

@@ -13,6 +13,7 @@
     "dist",
     "bin",
     "scripts",
+    "docs",
     "CLAUDE.md",
     "llms.txt",
     "AGENTS.md",

packages/shared/src/cli/commands/docs.ts

@@ -0,0 +1,61 @@
+import { Command } from "commander";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function findPackageRoot(): string {
+  let dir = __dirname;
+  while (dir !== path.parse(dir).root) {
+    if (fs.existsSync(path.join(dir, "package.json"))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  throw new Error("Could not find package root");
+}
+
+function runDocs(docPath?: string) {
+  const packageRoot = findPackageRoot();
+
+  if (!docPath) {
+    // Display llms.txt by default
+    const llmsPath = path.join(packageRoot, "llms.txt");
+
+    if (!fs.existsSync(llmsPath)) {
+      console.error("Error: llms.txt not found in package");
+      process.exit(1);
+    }
+
+    const content = fs.readFileSync(llmsPath, "utf-8");
+    console.log(content);
+    return;
+  }
+
+  // Handle path - remove leading /appkit/docs/ or /docs/ prefix
+  let normalizedPath = docPath;
+  normalizedPath = normalizedPath.replace(/^\/appkit\/docs\//, "");
+  normalizedPath = normalizedPath.replace(/^\/docs\//, "");
+  normalizedPath = normalizedPath.replace(/^docs\//, "");
+
+  const fullPath = path.join(packageRoot, "docs", normalizedPath);
+
+  if (!fs.existsSync(fullPath)) {
+    console.error(`Error: Documentation file not found: ${docPath}`);
+    console.error(`Tried: ${fullPath}`);
+    process.exit(1);
+  }
+
+  const content = fs.readFileSync(fullPath, "utf-8");
+  console.log(content);
+}
+
+export const docsCommand = new Command("docs")
+  .description("Display embedded documentation")
+  .argument(
+    "[path]",
+    "Path to specific documentation file (e.g., /appkit/docs/api/appkit-ui/components/Sidebar.md)",
+  )
+  .action(runDocs);

packages/shared/src/cli/commands/generate-types.ts

@@ -8,7 +8,7 @@ async function runGenerateTypes(
   rootDir?: string,
   outFile?: string,
   warehouseId?: string,
-  options?: { noCache?: boolean }
+  options?: { noCache?: boolean },
 ) {
   try {
     // Try to import the type generator from @databricks/appkit
@@ -26,7 +26,7 @@ async function runGenerateTypes(
       warehouseId || process.env.DATABRICKS_WAREHOUSE_ID;
     if (!resolvedWarehouseId) {
       console.error(
-        "Error: DATABRICKS_WAREHOUSE_ID is not set. Please provide it as an argument or environment variable."
+        "Error: DATABRICKS_WAREHOUSE_ID is not set. Please provide it as an argument or environment variable.",
       );
       process.exit(1);
     }
@@ -43,11 +43,9 @@ async function runGenerateTypes(
       error.message.includes("Cannot find module")
     ) {
       console.error(
-        "Error: The 'generate-types' command is only available in @databricks/appkit."
-      );
-      console.error(
-        "Please install @databricks/appkit to use this command."
+        "Error: The 'generate-types' command is only available in @databricks/appkit.",
       );
+      console.error("Please install @databricks/appkit to use this command.");
       process.exit(1);
     }
     throw error;
@@ -60,7 +58,7 @@ export const generateTypesCommand = new Command("generate-types")
   .argument(
     "[outFile]",
     "Output file path",
-    path.join(process.cwd(), "client/src/appKitTypes.d.ts")
+    path.join(process.cwd(), "client/src/appKitTypes.d.ts"),
   )
   .argument("[warehouseId]", "Databricks warehouse ID")
   .option("--no-cache", "Disable caching for type generation")

packages/shared/src/cli/commands/setup.ts

@@ -21,7 +21,12 @@ function findInstalledPackages() {
   const installed = [];
 
   for (const pkg of PACKAGES) {
-    const packagePath = path.join(cwd, "node_modules", pkg.name, "package.json");
+    const packagePath = path.join(
+      cwd,
+      "node_modules",
+      pkg.name,
+      "package.json",
+    );
     if (fs.existsSync(packagePath)) {
       installed.push(pkg);
     }

packages/shared/src/cli/index.ts

@@ -4,6 +4,7 @@ import { Command } from "commander";
 import { setupCommand } from "./commands/setup.js";
 import { generateTypesCommand } from "./commands/generate-types.js";
 import { lintCommand } from "./commands/lint.js";
+import { docsCommand } from "./commands/docs.js";
 
 const program = new Command();
 
@@ -16,5 +17,6 @@ program
 program.addCommand(setupCommand);
 program.addCommand(generateTypesCommand);
 program.addCommand(lintCommand);
+program.addCommand(docsCommand);
 
 program.parse();

pnpm-lock.yaml

@@ -23,7 +23,7 @@ const sharedPostinstall = path.join(
 if (isAppKitPackage) {
   if (fs.existsSync(sharedBin)) {
     pkg.bin = pkg.bin || {};
-    pkg.bin["appkit"] = "./bin/appkit.js";
+    pkg.bin.appkit = "./bin/appkit.js";
   }
   if (fs.existsSync(sharedPostinstall)) {
     pkg.scripts = pkg.scripts || {};
@@ -51,22 +51,42 @@ if (isAppKitPackage) {
   }
 }
 
-// Copy documentation from docs/build
+// Copy documentation from docs/build into tmp/docs/
 const docsBuildPath = path.join(__dirname, "../docs/build");
 
-// Copy llms.txt
-fs.copyFileSync(path.join(docsBuildPath, "llms.txt"), "tmp/llms.txt");
+// Copy all .md files and docs/ subdirectory from docs/build to tmp/docs
+fs.mkdirSync("tmp/docs", { recursive: true });
+
+// Copy all files and directories we want, preserving structure
+const itemsToCopy = fs.readdirSync(docsBuildPath);
+for (const item of itemsToCopy) {
+  const sourcePath = path.join(docsBuildPath, item);
+  const stat = fs.statSync(sourcePath);
+  
+  // Copy .md files and docs directory
+  if (item.endsWith('.md') || item === 'docs') {
+    const destPath = path.join("tmp/docs", item);
+    if (stat.isDirectory()) {
+      fs.cpSync(sourcePath, destPath, { recursive: true });
+    } else {
+      fs.copyFileSync(sourcePath, destPath);
+    }
+  }
+}
+
+// Process llms.txt (keep existing logic but update path replacement)
+const llmsSourcePath = path.join(docsBuildPath, "llms.txt");
+let llmsContent = fs.readFileSync(llmsSourcePath, "utf-8");
+
+// Replace /appkit/ with ./docs/ to match new structure
+llmsContent = llmsContent.replace(/\/appkit\//g, "./docs/");
+
+fs.writeFileSync("tmp/llms.txt", llmsContent);
 
 // Copy llms.txt as CLAUDE.md and AGENTS.md (npm pack doesn't support symlinks)
 fs.copyFileSync("tmp/llms.txt", "tmp/CLAUDE.md");
 fs.copyFileSync("tmp/llms.txt", "tmp/AGENTS.md");
 
-// Copy markdown documentation structure
-const docsPath = path.join(docsBuildPath, "docs");
-if (fs.existsSync(docsPath)) {
-  fs.cpSync(docsPath, "tmp/docs", { recursive: true });
-}
-
 fs.copyFileSync(path.join(__dirname, "../README.md"), "tmp/README.md");
 fs.copyFileSync(path.join(__dirname, "../LICENSE"), "tmp/LICENSE");
 fs.copyFileSync(path.join(__dirname, "../DCO"), "tmp/DCO");