geo-ai-search-optimization 1.0.0 → 1.0.2

package/README.md

@@ -25,11 +25,28 @@ npx geo-ai-search-optimization
 ```bash
 geo-ai-search-optimization
 geo-ai-search-optimization install
+geo-ai-search-optimization install --target ./tmp/custom-skills --json
 geo-ai-search-optimization where
-geo-ai-search-optimization scan ./my-site
+geo-ai-search-optimization doctor
+geo-ai-search-optimization init-llms ./site --site-name "Acme Docs" --site-url "https://example.com"
+geo-ai-search-optimization scan ./my-site --max-file-size 500000 --max-examples 3
+geo-ai-search-optimization scan ./my-site --json --out ./reports/geo-scan.json
+geo-ai-search-optimization version
 geo-ai-search-optimization help
 ```
 
+## New in 1.0.2
+
+- `init-llms` command for generating an `llms.txt` starter template
+- keeps the `1.0.1` CLI upgrades: `doctor`, custom `install --target`, and richer `scan` output controls
+
+## New in 1.0.1
+
+- `doctor` command for installation and environment checks
+- `install --target <dir>` for custom skill destinations
+- `scan --out <file>` to save reports
+- `scan --max-file-size` and `scan --max-examples` for tighter project scans
+
 ## Install location
 
 By default the skill is installed to:
@@ -42,6 +59,7 @@ Override with:
 - `CODEX_HOME`
 - `CODEX_SKILLS_DIR`
 - `GEO_SKILL_INSTALL_DIR`
+- `GEO_SKILL_SKIP_POSTINSTALL`
 
 ## Resource contents
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geo-ai-search-optimization",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Install and run a GEO-first, SEO-supported Codex skill for AI search optimization.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -1,9 +1,11 @@
-import { installSkill } from "./install-skill.js";
-import { getBundledSkillPath, getInstalledSkillPath, getSkillName, getSkillsDir } from "./paths.js";
-import { renderScanMarkdown, scanProject } from "./scan.js";
 import { fileURLToPath } from "node:url";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { installSkill } from "./install-skill.js";
+import { getBundledSkillPath, getInstalledSkillPath, getSkillName, getSkillsDir } from "./paths.js";
+import { renderScanMarkdown, scanProject, writeScanOutput } from "./scan.js";
+import { renderDoctorMarkdown, runDoctor } from "./doctor.js";
+import { createLlmsTxt } from "./llms-txt.js";
 
 let cachedVersion;
 
@@ -25,9 +27,11 @@ function printHelp() {
       "",
       "Usage:",
       "  geo-ai-search-optimization",
-      "  geo-ai-search-optimization install",
+      "  geo-ai-search-optimization install [--target <dir>] [--json]",
       "  geo-ai-search-optimization where",
-      "  geo-ai-search-optimization scan <project-path> [--json]",
+      "  geo-ai-search-optimization doctor [--json]",
+      "  geo-ai-search-optimization init-llms [target-dir] [--site-name <name>] [--site-url <url>] [--overwrite] [--json]",
+      "  geo-ai-search-optimization scan <project-path> [--json] [--out <file>] [--max-file-size <bytes>] [--max-examples <count>]",
       "  geo-ai-search-optimization version",
       "  geo-ai-search-optimization help",
       "",
@@ -40,6 +44,105 @@ function printHelp() {
   );
 }
 
+function getFlagValue(args, flagName) {
+  const index = args.indexOf(flagName);
+  if (index === -1) {
+    return null;
+  }
+  if (index === args.length - 1) {
+    throw new Error(`${flagName} requires a value`);
+  }
+  return args[index + 1];
+}
+
+function hasFlag(args, ...flagNames) {
+  return flagNames.some((flagName) => args.includes(flagName));
+}
+
+function parsePositiveInteger(value, flagName) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`${flagName} must be a positive integer`);
+  }
+  return parsed;
+}
+
+async function handleInstall(args) {
+  const targetDir = getFlagValue(args, "--target");
+  const outputJson = hasFlag(args, "--json");
+  const result = await installSkill({ targetDir, silent: outputJson });
+
+  if (outputJson) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  }
+}
+
+function handleWhere() {
+  process.stdout.write(
+    [
+      `skill: ${getSkillName()}`,
+      `bundled: ${getBundledSkillPath()}`,
+      `skillsDir: ${getSkillsDir()}`,
+      `installed: ${getInstalledSkillPath()}`
+    ].join("\n") + "\n"
+  );
+}
+
+async function handleDoctor(args) {
+  const report = await runDoctor();
+  if (hasFlag(args, "--json")) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+  process.stdout.write(renderDoctorMarkdown(report));
+}
+
+async function handleScan(args) {
+  const projectPath = args.find((value) => !value.startsWith("-"));
+  if (!projectPath) {
+    throw new Error("scan requires a project path");
+  }
+
+  const maxFileSizeValue = getFlagValue(args, "--max-file-size");
+  const maxExamplesValue = getFlagValue(args, "--max-examples");
+  const summary = await scanProject(projectPath, {
+    maxFileSize: maxFileSizeValue ? parsePositiveInteger(maxFileSizeValue, "--max-file-size") : undefined,
+    maxExamples: maxExamplesValue ? parsePositiveInteger(maxExamplesValue, "--max-examples") : undefined
+  });
+
+  const outputJson = hasFlag(args, "--json");
+  const renderedOutput = outputJson
+    ? `${JSON.stringify(summary, null, 2)}\n`
+    : renderScanMarkdown(summary);
+
+  const outputPath = getFlagValue(args, "--out");
+  if (outputPath) {
+    const resolvedOutputPath = await writeScanOutput(outputPath, renderedOutput);
+    process.stdout.write(`Saved scan output to ${resolvedOutputPath}\n`);
+    return;
+  }
+
+  process.stdout.write(renderedOutput);
+}
+
+async function handleInitLlms(args) {
+  const targetDir = args.find((value) => !value.startsWith("-")) || ".";
+  const outputJson = hasFlag(args, "--json");
+  const result = await createLlmsTxt({
+    targetDir,
+    siteName: getFlagValue(args, "--site-name"),
+    siteUrl: getFlagValue(args, "--site-url"),
+    overwrite: hasFlag(args, "--overwrite")
+  });
+
+  if (outputJson) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+
+  process.stdout.write(`Created llms.txt at ${result.outputPath}\n`);
+}
+
 export async function runCli(args = []) {
   const [command = "install", ...rest] = args;
 
@@ -54,35 +157,27 @@ export async function runCli(args = []) {
   }
 
   if (command === "install") {
-    await installSkill();
+    await handleInstall(rest);
     return;
   }
 
   if (command === "where") {
-    process.stdout.write(
-      [
-        `skill: ${getSkillName()}`,
-        `bundled: ${getBundledSkillPath()}`,
-        `skillsDir: ${getSkillsDir()}`,
-        `installed: ${getInstalledSkillPath()}`
-      ].join("\n") + "\n"
-    );
+    handleWhere();
+    return;
+  }
+
+  if (command === "doctor") {
+    await handleDoctor(rest);
+    return;
+  }
+
+  if (command === "init-llms") {
+    await handleInitLlms(rest);
     return;
   }
 
   if (command === "scan") {
-    const projectPath = rest.find((value) => !value.startsWith("-"));
-    if (!projectPath) {
-      throw new Error("scan requires a project path");
-    }
-
-    const outputJson = rest.includes("--json");
-    const summary = await scanProject(projectPath);
-    if (outputJson) {
-      process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
-    } else {
-      process.stdout.write(renderScanMarkdown(summary));
-    }
+    await handleScan(rest);
     return;
   }
 

package/src/doctor.js

@@ -0,0 +1,140 @@
+import fs from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { getBundledSkillPath, getInstalledSkillPath, getSkillName, getSkillsDir } from "./paths.js";
+
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function findExistingParent(targetPath) {
+  let current = path.resolve(targetPath);
+
+  while (true) {
+    if (await pathExists(current)) {
+      return current;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return current;
+    }
+    current = parent;
+  }
+}
+
+async function checkWritable(targetPath) {
+  const existingParent = await findExistingParent(targetPath);
+
+  try {
+    await fs.access(existingParent, fsConstants.W_OK);
+    return {
+      ok: true,
+      checkedPath: existingParent
+    };
+  } catch {
+    return {
+      ok: false,
+      checkedPath: existingParent
+    };
+  }
+}
+
+export async function runDoctor() {
+  const bundledPath = getBundledSkillPath();
+  const installedPath = getInstalledSkillPath();
+  const skillsDir = getSkillsDir();
+
+  const [bundledExists, installedExists, writableCheck] = await Promise.all([
+    pathExists(bundledPath),
+    pathExists(installedPath),
+    checkWritable(skillsDir)
+  ]);
+
+  return {
+    skill: getSkillName(),
+    nodeVersion: process.version,
+    platform: process.platform,
+    bundledPath,
+    installedPath,
+    skillsDir,
+    envOverrides: {
+      CODEX_HOME: process.env.CODEX_HOME || null,
+      CODEX_SKILLS_DIR: process.env.CODEX_SKILLS_DIR || null,
+      GEO_SKILL_INSTALL_DIR: process.env.GEO_SKILL_INSTALL_DIR || null
+    },
+    checks: {
+      bundledSkillPresent: bundledExists,
+      installedSkillPresent: installedExists,
+      skillsDirWritable: writableCheck.ok,
+      skillsDirWritableCheckPath: writableCheck.checkedPath
+    },
+    recommendations: buildDoctorRecommendations({
+      bundledExists,
+      installedExists,
+      writableCheck,
+      skillsDir
+    })
+  };
+}
+
+function buildDoctorRecommendations(context) {
+  const recommendations = [];
+
+  if (!context.bundledExists) {
+    recommendations.push("Bundled skill files are missing. Reinstall the npm package before using the CLI.");
+  }
+  if (!context.installedExists) {
+    recommendations.push("The skill is not installed into the Codex skills directory yet. Run `geo-ai-search-optimization install`.");
+  }
+  if (!context.writableCheck.ok) {
+    recommendations.push(
+      `The target skills directory is not writable from this environment. Use --target or set CODEX_SKILLS_DIR to a writable location.`
+    );
+  }
+  if (recommendations.length === 0) {
+    recommendations.push("Environment looks healthy. You can install, scan, and iterate on the skill from this machine.");
+  }
+
+  return recommendations;
+}
+
+export function renderDoctorMarkdown(report) {
+  const lines = [
+    "# GEO CLI Doctor",
+    "",
+    `- Skill: \`${report.skill}\``,
+    `- Node: \`${report.nodeVersion}\``,
+    `- Platform: \`${report.platform}\``,
+    `- Bundled path: \`${report.bundledPath}\``,
+    `- Installed path: \`${report.installedPath}\``,
+    `- Skills dir: \`${report.skillsDir}\``,
+    "",
+    "## Checks",
+    "",
+    `- bundledSkillPresent: \`${report.checks.bundledSkillPresent}\``,
+    `- installedSkillPresent: \`${report.checks.installedSkillPresent}\``,
+    `- skillsDirWritable: \`${report.checks.skillsDirWritable}\` via \`${report.checks.skillsDirWritableCheckPath}\``,
+    "",
+    "## Environment Overrides",
+    "",
+    `- CODEX_HOME: \`${report.envOverrides.CODEX_HOME ?? "unset"}\``,
+    `- CODEX_SKILLS_DIR: \`${report.envOverrides.CODEX_SKILLS_DIR ?? "unset"}\``,
+    `- GEO_SKILL_INSTALL_DIR: \`${report.envOverrides.GEO_SKILL_INSTALL_DIR ?? "unset"}\``,
+    "",
+    "## Recommendations",
+    ""
+  ];
+
+  for (const recommendation of report.recommendations) {
+    lines.push(`- ${recommendation}`);
+  }
+
+  return `${lines.join("\n")}\n`;
+}

package/src/index.js

@@ -1,3 +1,5 @@
 export { installSkill } from "./install-skill.js";
 export { runCli } from "./cli.js";
-export { scanProject, renderScanMarkdown } from "./scan.js";
+export { runDoctor, renderDoctorMarkdown } from "./doctor.js";
+export { createLlmsTxt } from "./llms-txt.js";
+export { scanProject, renderScanMarkdown, writeScanOutput } from "./scan.js";

package/src/install-skill.js

@@ -28,7 +28,8 @@ export async function installSkill(options = {}) {
     skill: getSkillName(),
     installedAt: new Date().toISOString(),
     installedFrom: sourceDir,
-    packageName: "geo-ai-search-optimization"
+    packageName: "geo-ai-search-optimization",
+    targetDir
   };
 
   await fs.writeFile(
@@ -44,6 +45,7 @@ export async function installSkill(options = {}) {
   return {
     targetDir,
     sourceDir,
-    skillName: getSkillName()
+    skillName: getSkillName(),
+    manifest
   };
 }

package/src/llms-txt.js

@@ -0,0 +1,76 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+async function pathExists(targetPath) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function buildLlmsTxtContent({ siteName, siteUrl }) {
+  const resolvedSiteName = siteName || "Your Site Name";
+  const resolvedSiteUrl = siteUrl || "https://example.com";
+
+  return [
+    `# ${resolvedSiteName}`,
+    "",
+    `> GEO-first site profile for AI assistants and answer engines.`,
+    "",
+    `Canonical: ${resolvedSiteUrl}`,
+    "",
+    "## About",
+    "",
+    "- Summarize what this site does in 1-2 sentences.",
+    "- Describe the primary audience and core use cases.",
+    "- Mention what makes the content or product uniquely trustworthy.",
+    "",
+    "## Priority URLs",
+    "",
+    `- ${resolvedSiteUrl}/`,
+    `- ${resolvedSiteUrl}/pricing`,
+    `- ${resolvedSiteUrl}/docs`,
+    `- ${resolvedSiteUrl}/blog`,
+    "",
+    "## Recommended Sources",
+    "",
+    "- Link to pages with first-party research, methodology, benchmarks, or clear product facts.",
+    "- Prefer canonical pages over campaign or temporary URLs.",
+    "",
+    "## AI Assistant Guidance",
+    "",
+    "- Use the latest canonical URLs when citing this site.",
+    "- Prefer pages with explicit dates, authors, reviewers, or methodology notes.",
+    "- Avoid summarizing outdated pages when newer versions exist.",
+    "",
+    "## Update Policy",
+    "",
+    "- Replace this section with the site’s actual content freshness and review cadence.",
+    ""
+  ].join("\n");
+}
+
+export async function createLlmsTxt(options = {}) {
+  const targetDir = path.resolve(options.targetDir || ".");
+  const outputPath = path.join(targetDir, "llms.txt");
+  const overwrite = Boolean(options.overwrite);
+
+  if (!overwrite && (await pathExists(outputPath))) {
+    throw new Error(`llms.txt already exists at ${outputPath}. Use --overwrite to replace it.`);
+  }
+
+  await fs.mkdir(targetDir, { recursive: true });
+  const content = buildLlmsTxtContent({
+    siteName: options.siteName,
+    siteUrl: options.siteUrl
+  });
+  await fs.writeFile(outputPath, content, "utf8");
+
+  return {
+    outputPath,
+    siteName: options.siteName || "Your Site Name",
+    siteUrl: options.siteUrl || "https://example.com"
+  };
+}

package/src/scan.js

@@ -207,6 +207,13 @@ export async function scanProject(rootInput, options = {}) {
   return summary;
 }
 
+export async function writeScanOutput(outputPath, content) {
+  const resolvedPath = path.resolve(outputPath);
+  await fs.mkdir(path.dirname(resolvedPath), { recursive: true });
+  await fs.writeFile(resolvedPath, content, "utf8");
+  return resolvedPath;
+}
+
 export function renderScanMarkdown(summary) {
   const lines = [
     "# GEO Signal Scan",