geo-ai-search-optimization 1.3.7 → 1.3.9

package/README.md

@@ -886,6 +886,22 @@ geo-ai-search-optimization help
 - `src/cli-agent-execution-commands.js` 与 `src/cli-planning-delivery-commands.js` 现在改用声明式组合，减少重复的 `create / render / write` handler 模板代码
 - CLI 架构从“按命令族拆文件”进一步推进到“adapter + shared composition”模式
 
+## New in 1.3.8
+
+- 继续把共享组合器推广到 `flow` 与 `site-ops` 两层
+- `src/cli-shared.js` 新增 `createStructuredOutputCommandHandler`
+- `src/cli-flow-commands.js` 现在统一通过组合器编排 `auto-flow / agent-orchestrator / agent-resume / agent-continue / agent-state-pack / agent-session`
+- `src/cli-site-ops-commands.js` 现在统一通过组合器编排 `doctor / quick-start / onboard / onboard-url / audit / scan`
+- CLI 架构进一步收敛到“命令族 adapter + shared composition primitives”的模式
+
+## New in 1.3.9
+
+- 继续把“直接执行型命令”也纳入共享组合模式
+- `src/cli-shared.js` 新增 `createActionCommandHandler`
+- `src/cli-shell-commands.js` 里的 `install` 已改成声明式 action 组合
+- `src/cli-site-ops-commands.js` 里的 `init-llms / init-schema` 已改成声明式 action 组合
+- CLI 现在同时覆盖 artifact、structured-output、action 三类共享 composition primitives
+
 ## New in 1.2.20
 
 - 新增 `agent-continue`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geo-ai-search-optimization",
-  "version": "1.3.7",
+  "version": "1.3.9",
   "description": "Install and run a Generative Engine Optimization (GEO)-first, SEO-supported Codex skill for website optimization.",
   "type": "module",
   "bin": {

package/src/cli-flow-commands.js

@@ -17,11 +17,12 @@ import {
 } from "./agent-state-pack.js";
 import { createAgentSession, renderAgentSessionMarkdown, writeAgentSessionOutput } from "./agent-session.js";
 import {
+  createArtifactCommandHandler,
+  createStructuredOutputCommandHandler,
   getFlagValue,
   getJsonCapableFormat,
   getRequiredInput,
-  hasFlag,
-  writeOrPrintArtifact
+  hasFlag
 } from "./cli-shared.js";
 
 export const FLOW_HELP_LINES = [
@@ -33,105 +34,80 @@ export const FLOW_HELP_LINES = [
   "  geo-ai-search-optimization agent-session <input> [--intent <auto|diagnose|guide|execute|share|closeout>] [--json] [--out <file>]"
 ];
 
-async function handleAutoFlow(args) {
-  const input = getRequiredInput(args, "auto-flow");
-  const flow = await createAutoFlow(input, {
-    intent: getFlagValue(args, "--intent")
-  });
-  const outputJson = hasFlag(args, "--json");
-  const renderedOutput = outputJson ? `${JSON.stringify(flow, null, 2)}\n` : renderAutoFlowMarkdown(flow);
-  const outputPath = getFlagValue(args, "--out");
-
-  if (outputPath) {
-    const resolvedOutputPath = await writeAutoFlowOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存 auto-flow 结果：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  process.stdout.write(renderedOutput);
-}
+const handleAutoFlow = createStructuredOutputCommandHandler({
+  commandLabel: "auto-flow",
+  execute: async (args) => {
+    const input = getRequiredInput(args, "auto-flow");
+    return createAutoFlow(input, {
+      intent: getFlagValue(args, "--intent")
+    });
+  },
+  renderMarkdown: renderAutoFlowMarkdown,
+  writeOutput: writeAutoFlowOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
 
-async function handleAgentOrchestrator(args) {
-  const input = getRequiredInput(args, "agent-orchestrator");
-  const artifact = await createAgentOrchestrator(input, {
+const handleAgentOrchestrator = createArtifactCommandHandler({
+  commandName: "agent-orchestrator",
+  commandLabel: "agent-orchestrator",
+  createArtifact: createAgentOrchestrator,
+  renderMarkdown: renderAgentOrchestratorMarkdown,
+  writeOutput: writeAgentOrchestratorOutput,
+  getOptions: (args) => ({
     intent: getFlagValue(args, "--intent"),
     format: getJsonCapableFormat(args)
-  });
-  return writeOrPrintArtifact({
-    args,
-    commandName: "agent-orchestrator",
-    artifact,
-    renderMarkdown: renderAgentOrchestratorMarkdown,
-    writeOutput: writeAgentOrchestratorOutput,
-    outputJson: artifact.format === "json"
-  });
-}
+  })
+});
 
-async function handleAgentResume(args) {
-  const input = getRequiredInput(args, "agent-resume");
-  const artifact = await createAgentResume(input, {
+const handleAgentResume = createArtifactCommandHandler({
+  commandName: "agent-resume",
+  commandLabel: "agent-resume",
+  createArtifact: createAgentResume,
+  renderMarkdown: renderAgentResumeMarkdown,
+  writeOutput: writeAgentResumeOutput,
+  getOptions: (args) => ({
     intent: getFlagValue(args, "--intent"),
     format: getJsonCapableFormat(args)
-  });
-  return writeOrPrintArtifact({
-    args,
-    commandName: "agent-resume",
-    artifact,
-    renderMarkdown: renderAgentResumeMarkdown,
-    writeOutput: writeAgentResumeOutput,
-    outputJson: artifact.format === "json"
-  });
-}
+  })
+});
 
-async function handleAgentContinue(args) {
-  const input = getRequiredInput(args, "agent-continue");
-  const artifact = await createAgentContinue(input, {
+const handleAgentContinue = createArtifactCommandHandler({
+  commandName: "agent-continue",
+  commandLabel: "agent-continue",
+  createArtifact: createAgentContinue,
+  renderMarkdown: renderAgentContinueMarkdown,
+  writeOutput: writeAgentContinueOutput,
+  getOptions: (args) => ({
     intent: getFlagValue(args, "--intent"),
     format: getJsonCapableFormat(args)
-  });
-  return writeOrPrintArtifact({
-    args,
-    commandName: "agent-continue",
-    artifact,
-    renderMarkdown: renderAgentContinueMarkdown,
-    writeOutput: writeAgentContinueOutput,
-    outputJson: artifact.format === "json"
-  });
-}
+  })
+});
 
-async function handleAgentStatePack(args) {
-  const input = getRequiredInput(args, "agent-state-pack");
-  const artifact = await createAgentStatePack(input, {
+const handleAgentStatePack = createArtifactCommandHandler({
+  commandName: "agent-state-pack",
+  commandLabel: "agent-state-pack",
+  createArtifact: createAgentStatePack,
+  renderMarkdown: renderAgentStatePackMarkdown,
+  writeOutput: writeAgentStatePackOutput,
+  getOptions: (args) => ({
     intent: getFlagValue(args, "--intent"),
     format: getJsonCapableFormat(args),
     currentTaskId: getFlagValue(args, "--current"),
     completedPacketIds: getFlagValue(args, "--completed"),
     blockedReasons: getFlagValue(args, "--blocked")
-  });
-  return writeOrPrintArtifact({
-    args,
-    commandName: "agent-state-pack",
-    artifact,
-    renderMarkdown: renderAgentStatePackMarkdown,
-    writeOutput: writeAgentStatePackOutput,
-    outputJson: artifact.format === "json"
-  });
-}
+  })
+});
 
-async function handleAgentSession(args) {
-  const input = getRequiredInput(args, "agent-session");
-  const artifact = await createAgentSession(input, {
+const handleAgentSession = createArtifactCommandHandler({
+  commandName: "agent-session",
+  commandLabel: "agent-session",
+  createArtifact: createAgentSession,
+  renderMarkdown: renderAgentSessionMarkdown,
+  writeOutput: writeAgentSessionOutput,
+  getOptions: (args) => ({
     intent: getFlagValue(args, "--intent")
-  });
-  return writeOrPrintArtifact({
-    args,
-    commandName: "agent-session",
-    artifact,
-    renderMarkdown: renderAgentSessionMarkdown,
-    writeOutput: writeAgentSessionOutput,
-    outputJson: hasFlag(args, "--json")
-  });
-}
+  })
+});
 
 export const FLOW_COMMAND_HANDLERS = {
   "auto-flow": handleAutoFlow,

package/src/cli-shared.js

@@ -90,3 +90,46 @@ export function createPackCommandHandler({
     process.stdout.write(renderMarkdown(pack));
   };
 }
+
+export function createStructuredOutputCommandHandler({
+  commandLabel,
+  execute,
+  renderMarkdown,
+  writeOutput,
+  getOutputJson
+}) {
+  return async function structuredOutputCommandHandler(args) {
+    const result = await execute(args);
+    const outputJson = getOutputJson ? getOutputJson(args, result) : hasFlag(args, "--json");
+    const renderedOutput = outputJson ? `${JSON.stringify(result, null, 2)}\n` : renderMarkdown(result);
+    const outputPath = getFlagValue(args, "--out");
+
+    if (outputPath) {
+      const resolvedOutputPath = await writeOutput(outputPath, renderedOutput);
+      process.stdout.write(`已保存 ${commandLabel} 结果：${resolvedOutputPath}\n`);
+      return;
+    }
+
+    process.stdout.write(renderedOutput);
+  };
+}
+
+export function createActionCommandHandler({
+  execute,
+  getOutputJson,
+  renderText
+}) {
+  return async function actionCommandHandler(args) {
+    const result = await execute(args);
+    const outputJson = getOutputJson ? getOutputJson(args, result) : hasFlag(args, "--json");
+
+    if (outputJson) {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+      return;
+    }
+
+    if (renderText) {
+      process.stdout.write(renderText(result, args));
+    }
+  };
+}

package/src/cli-shell-commands.js

@@ -1,4 +1,4 @@
-import { getFlagValue, hasFlag } from "./cli-shared.js";
+import { createActionCommandHandler, getFlagValue, hasFlag } from "./cli-shared.js";
 import { installSkill } from "./install-skill.js";
 import { getBundledSkillPath, getInstalledSkillPath, getSkillName, getSkillsDir } from "./paths.js";
 import { listBundledSkills, renderBundledSkillsMarkdown } from "./skills.js";
@@ -9,15 +9,16 @@ export const SHELL_HELP_LINES = [
   "  geo-ai-search-optimization where"
 ];
 
-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`);
-  }
-}
+const handleInstall = createActionCommandHandler({
+  execute: async (args) => {
+    const outputJson = hasFlag(args, "--json");
+    return installSkill({
+      targetDir: getFlagValue(args, "--target"),
+      silent: outputJson
+    });
+  },
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
 
 async function handleSkills(args) {
   const bundle = await listBundledSkills();

package/src/cli-site-ops-commands.js

@@ -1,5 +1,11 @@
 import { auditProject, renderAuditMarkdown, writeAuditOutput } from "./audit.js";
-import { getFlagValue, hasFlag, parsePositiveInteger } from "./cli-shared.js";
+import {
+  createActionCommandHandler,
+  createStructuredOutputCommandHandler,
+  getFlagValue,
+  hasFlag,
+  parsePositiveInteger
+} from "./cli-shared.js";
 import { renderDoctorMarkdown, runDoctor } from "./doctor.js";
 import {
   renderInteractiveOnboardingMarkdown,
@@ -23,171 +29,124 @@ export const SITE_OPS_HELP_LINES = [
   "  geo-ai-search-optimization scan <project-path> [--json] [--out <file>] [--max-file-size <bytes>] [--max-examples <count>]"
 ];
 
-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 handleQuickStart(args) {
-  const outputJson = hasFlag(args, "--json");
-  const plan = createQuickStartPlan({});
-  const renderedOutput = outputJson ? `${JSON.stringify(plan, null, 2)}\n` : renderQuickStartMarkdown(plan);
-  const outputPath = getFlagValue(args, "--out");
-
-  if (outputPath) {
-    const resolvedOutputPath = await writeQuickStartOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存 quick start 输出：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  process.stdout.write(renderedOutput);
-}
-
-async function handleInteractiveOnboard(args) {
-  const report = await runInteractiveOnboarding({
-    url: getFlagValue(args, "--url"),
-    goal: getFlagValue(args, "--goal"),
-    existingAssets: getFlagValue(args, "--existing-assets")
-  });
-
-  const outputJson = hasFlag(args, "--json");
-  const renderedOutput = outputJson
-    ? `${JSON.stringify(report, null, 2)}\n`
-    : renderInteractiveOnboardingMarkdown(report);
-  const outputPath = getFlagValue(args, "--out");
-
-  if (outputPath) {
-    const resolvedOutputPath = await writeInteractiveOnboardingOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存交互式 onboarding 结果：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  process.stdout.write(renderedOutput);
-}
-
-async function handleOnboardUrl(args) {
-  const inputUrl = args.find((value) => !value.startsWith("-"));
-  if (!inputUrl) {
-    throw new Error("onboard-url requires a website URL");
-  }
-
-  const report = await analyzeWebsiteUrl(inputUrl, {});
-  const outputJson = hasFlag(args, "--json");
-  const renderedOutput = outputJson
-    ? `${JSON.stringify(report, null, 2)}\n`
-    : `${renderWebsiteOnboardingMarkdown(report)}\n`;
-  const outputPath = getFlagValue(args, "--out");
-
-  if (outputPath) {
-    const resolvedOutputPath = await writeWebsiteOnboardingOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存 onboarding 结果：${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`);
-}
-
-async function handleInitSchema(args) {
-  const [schemaType, ...rest] = args;
-  if (!schemaType || schemaType.startsWith("-")) {
-    throw new Error("init-schema requires a schema type");
-  }
-
-  const targetDir = rest.find((value) => !value.startsWith("-")) || ".";
-  const outputJson = hasFlag(rest, "--json");
-  const result = await createSchemaTemplate({
-    schemaType,
-    targetDir,
-    siteUrl: getFlagValue(rest, "--site-url"),
-    overwrite: hasFlag(rest, "--overwrite")
-  });
-
-  if (outputJson) {
-    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-    return;
-  }
-
-  process.stdout.write(`Created ${result.schemaType} schema template at ${result.outputPath}\n`);
-}
-
-async function handleAudit(args) {
-  const projectPath = args.find((value) => !value.startsWith("-"));
-  if (!projectPath) {
-    throw new Error("audit requires a project path");
-  }
-
-  const report = await auditProject(projectPath, {
-    maxFileSize: getFlagValue(args, "--max-file-size")
-      ? parsePositiveInteger(getFlagValue(args, "--max-file-size"), "--max-file-size")
-      : undefined,
-    maxExamples: getFlagValue(args, "--max-examples")
-      ? parsePositiveInteger(getFlagValue(args, "--max-examples"), "--max-examples")
-      : undefined
-  });
-
-  const outputJson = hasFlag(args, "--json");
-  const renderedOutput = outputJson
-    ? `${JSON.stringify(report, null, 2)}\n`
-    : `${renderAuditMarkdown(report)}\n`;
-  const outputPath = getFlagValue(args, "--out");
-
-  if (outputPath) {
-    const resolvedOutputPath = await writeAuditOutput(outputPath, renderedOutput);
-    process.stdout.write(`已保存审计结果：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  process.stdout.write(renderedOutput);
-}
-
-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(`已保存扫描结果：${resolvedOutputPath}\n`);
-    return;
-  }
-
-  process.stdout.write(renderedOutput);
-}
+const passthroughWriteOutput = async (outputPath) => outputPath;
+
+const handleDoctor = createStructuredOutputCommandHandler({
+  commandLabel: "doctor",
+  execute: async () => runDoctor(),
+  renderMarkdown: renderDoctorMarkdown,
+  writeOutput: passthroughWriteOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleQuickStart = createStructuredOutputCommandHandler({
+  commandLabel: "quick start",
+  execute: async () => createQuickStartPlan({}),
+  renderMarkdown: renderQuickStartMarkdown,
+  writeOutput: writeQuickStartOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleInteractiveOnboard = createStructuredOutputCommandHandler({
+  commandLabel: "交互式 onboarding",
+  execute: async (args) =>
+    runInteractiveOnboarding({
+      url: getFlagValue(args, "--url"),
+      goal: getFlagValue(args, "--goal"),
+      existingAssets: getFlagValue(args, "--existing-assets")
+    }),
+  renderMarkdown: renderInteractiveOnboardingMarkdown,
+  writeOutput: writeInteractiveOnboardingOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleOnboardUrl = createStructuredOutputCommandHandler({
+  commandLabel: "onboarding",
+  execute: async (args) => {
+    const inputUrl = args.find((value) => !value.startsWith("-"));
+    if (!inputUrl) {
+      throw new Error("onboard-url requires a website URL");
+    }
+
+    return analyzeWebsiteUrl(inputUrl, {});
+  },
+  renderMarkdown: (report) => `${renderWebsiteOnboardingMarkdown(report)}\n`,
+  writeOutput: writeWebsiteOnboardingOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleInitLlms = createActionCommandHandler({
+  execute: async (args) =>
+    createLlmsTxt({
+      targetDir: args.find((value) => !value.startsWith("-")) || ".",
+      siteName: getFlagValue(args, "--site-name"),
+      siteUrl: getFlagValue(args, "--site-url"),
+      overwrite: hasFlag(args, "--overwrite")
+    }),
+  getOutputJson: (args) => hasFlag(args, "--json"),
+  renderText: (result) => `Created llms.txt at ${result.outputPath}\n`
+});
+
+const handleInitSchema = createActionCommandHandler({
+  execute: async (args) => {
+    const [schemaType, ...rest] = args;
+    if (!schemaType || schemaType.startsWith("-")) {
+      throw new Error("init-schema requires a schema type");
+    }
+
+    return createSchemaTemplate({
+      schemaType,
+      targetDir: rest.find((value) => !value.startsWith("-")) || ".",
+      siteUrl: getFlagValue(rest, "--site-url"),
+      overwrite: hasFlag(rest, "--overwrite")
+    });
+  },
+  getOutputJson: (args) => hasFlag(args, "--json"),
+  renderText: (result) => `Created ${result.schemaType} schema template at ${result.outputPath}\n`
+});
+
+const handleAudit = createStructuredOutputCommandHandler({
+  commandLabel: "审计",
+  execute: async (args) => {
+    const projectPath = args.find((value) => !value.startsWith("-"));
+    if (!projectPath) {
+      throw new Error("audit requires a project path");
+    }
+
+    return auditProject(projectPath, {
+      maxFileSize: getFlagValue(args, "--max-file-size")
+        ? parsePositiveInteger(getFlagValue(args, "--max-file-size"), "--max-file-size")
+        : undefined,
+      maxExamples: getFlagValue(args, "--max-examples")
+        ? parsePositiveInteger(getFlagValue(args, "--max-examples"), "--max-examples")
+        : undefined
+    });
+  },
+  renderMarkdown: (report) => `${renderAuditMarkdown(report)}\n`,
+  writeOutput: writeAuditOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
+
+const handleScan = createStructuredOutputCommandHandler({
+  commandLabel: "扫描",
+  execute: async (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");
+
+    return scanProject(projectPath, {
+      maxFileSize: maxFileSizeValue ? parsePositiveInteger(maxFileSizeValue, "--max-file-size") : undefined,
+      maxExamples: maxExamplesValue ? parsePositiveInteger(maxExamplesValue, "--max-examples") : undefined
+    });
+  },
+  renderMarkdown: renderScanMarkdown,
+  writeOutput: writeScanOutput,
+  getOutputJson: (args) => hasFlag(args, "--json")
+});
 
 export const SITE_OPS_COMMAND_HANDLERS = {
   doctor: handleDoctor,