helpshelf 0.4.0 → 0.4.2

package/dist/index.js

@@ -8,7 +8,7 @@ import { Command } from "commander";
 
 // src/commands/scan.ts
 import { resolve, join as join8, relative as relative4 } from "path";
-import { readFileSync as readFileSync2, writeFileSync, existsSync as existsSync8, mkdirSync, readdirSync as readdirSync4 } from "fs";
+import { readFileSync as readFileSync2, writeFileSync, existsSync as existsSync8, mkdirSync, readdirSync as readdirSync4, statSync as statSync3 } from "fs";
 import { createInterface } from "readline";
 import { basename as basename2 } from "path";
 import chalk from "chalk";
@@ -915,6 +915,36 @@ function generateDepFaqs(deps) {
 }
 
 // src/commands/scan.ts
+function isICloudEvicted(filePath) {
+  try {
+    const stat = statSync3(filePath);
+    return stat.isFile() && stat.size > 0 && stat.blocks === 0;
+  } catch {
+    return false;
+  }
+}
+function checkICloudStatus(dir, log) {
+  const criticalFiles = ["package.json", "README.md", ".env", ".env.example", "tsconfig.json", "pyproject.toml"];
+  const evictedFiles = [];
+  for (const file of criticalFiles) {
+    const filePath = join8(dir, file);
+    if (existsSync8(filePath) && isICloudEvicted(filePath)) {
+      evictedFiles.push(file);
+    }
+  }
+  if (evictedFiles.length > 0) {
+    log(chalk.yellow.bold("\u26A0  iCloud Drive detected \u2014 key files are not downloaded locally:"));
+    for (const file of evictedFiles) {
+      log(chalk.yellow(`   \u2022 ${file}`));
+    }
+    log();
+    log(chalk.dim('   To fix, open Finder \u2192 right-click the project folder \u2192 "Download Now"'));
+    log(chalk.dim("   Or move the project out of Desktop/Documents to a non-iCloud folder."));
+    log();
+    return true;
+  }
+  return false;
+}
 async function scanCommand(options) {
   const startTime = Date.now();
   const projectDir = resolve(options.dir);
@@ -928,6 +958,10 @@ async function scanCommand(options) {
     console.error(chalk.red(`Directory not found: ${projectDir}`));
     process.exit(1);
   }
+  const hasEvictedFiles = checkICloudStatus(projectDir, log);
+  if (hasEvictedFiles) {
+    log(chalk.yellow("   Scanning anyway, but results will be incomplete.\n"));
+  }
   const spinner = ora("Reading project metadata...").start();
   const project = scanProjectMeta(projectDir);
   spinner.succeed(`Project: ${chalk.cyan(project.name)}${project.version ? ` v${project.version}` : ""}`);
@@ -1579,7 +1613,12 @@ function readDocsDirectory(dir) {
   const files = readdirSync5(dir).filter((f) => f.endsWith(".md"));
   const articles = [];
   for (const file of files) {
-    const content = readFileSync3(join9(dir, file), "utf-8");
+    let content;
+    try {
+      content = readFileSync3(join9(dir, file), "utf-8");
+    } catch {
+      continue;
+    }
     const slug = basename3(file, ".md");
     const { frontmatter, body } = parseFrontmatter2(content);
     const title = frontmatter.title || slug.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
@@ -1675,10 +1714,14 @@ async function initCommand() {
   }
   const gitignorePath = join10(dir, ".gitignore");
   if (existsSync10(gitignorePath)) {
-    const gitignore = readFileSync4(gitignorePath, "utf-8");
-    if (!gitignore.includes(".helpshelf/snapshot.json")) {
-      writeFileSync3(gitignorePath, gitignore.trimEnd() + "\n\n# HelpShelf\n.helpshelf/snapshot.json\n");
-      console.log(chalk3.green("  \u2713"), "Added .helpshelf/snapshot.json to .gitignore");
+    try {
+      const gitignore = readFileSync4(gitignorePath, "utf-8");
+      if (!gitignore.includes(".helpshelf/snapshot.json")) {
+        writeFileSync3(gitignorePath, gitignore.trimEnd() + "\n\n# HelpShelf\n.helpshelf/snapshot.json\n");
+        console.log(chalk3.green("  \u2713"), "Added .helpshelf/snapshot.json to .gitignore");
+      }
+    } catch {
+      console.log(chalk3.yellow("  \u26A0"), "Could not read .gitignore (file may be on iCloud)");
     }
   }
   console.log();
@@ -1768,7 +1811,7 @@ async function screenshotCommand(options) {
 
 // src/index.ts
 var program = new Command();
-program.name("helpshelf").description("AI-agent toolkit for auto-generating support docs").version("0.4.0");
+program.name("helpshelf").description("AI-agent toolkit for auto-generating support docs").version("0.4.2");
 program.command("scan").description("Scan your codebase \u2192 snapshot.json + docs-template.json").option("-d, --dir <path>", "Project directory to scan", ".").option("-o, --output <path>", "Output file path", ".helpshelf/snapshot.json").option("--no-readme", "Skip README parsing").option("--no-deps", "Skip dependency analysis").option("--no-api", "Skip API route detection").option("--no-env", "Skip environment variable detection").option("--verbose", "Show detailed scan output").option("--quiet", "Suppress output (for programmatic use)").option("-u, --url <url>", "Also capture screenshots from a running app (e.g., http://localhost:3000)").option("-e, --email <email>", "Login email for screenshot auth").option("-p, --password <password>", "Login password for screenshot auth").option("-m, --max-pages <n>", "Max pages to screenshot", "20").action(scanCommand);
 program.command("screenshot").description("Capture screenshots of your running app's pages").requiredOption("-u, --url <url>", "URL of your running app (e.g., http://localhost:3000)").option("-e, --email <email>", "Login email for authenticated pages").option("-p, --password <password>", "Login password").option("-s, --snapshot <path>", "Path to scan snapshot (for route intelligence)", ".helpshelf/snapshot.json").option("-o, --output <path>", "Output directory for screenshots", ".helpshelf/screenshots").option("-m, --max-pages <n>", "Maximum pages to capture", "20").action(screenshotCommand);
 program.command("push").description("Push docs to HelpShelf (creates account if needed)").option("--email <email>", "HelpShelf account email").option("--domain <domain>", "Your app domain (for help center URL)").option("--docs-dir <path>", "Directory containing markdown docs", ".helpshelf/docs").option("--site <hash>", "Existing HelpShelf site hash").option("--api-key <key>", "Existing HelpShelf API key").option("--api-url <url>", "HelpShelf API URL", "https://app.helpshelf.com").option("--dry-run", "Preview what would be pushed without sending").action(pushCommand);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helpshelf",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Scan your codebase and auto-generate support docs for HelpShelf",
   "type": "module",
   "bin": {