@clue-ai/cli 0.0.5 → 0.0.7

package/src/setup-prepare.mjs

@@ -1,170 +1,384 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import {
-	buildSemanticWorkflowRequestFromFlags,
-	writeSemanticWorkflow,
+  buildSemanticWorkflowRequestFromFlags,
+  writeSemanticWorkflow,
 } from "./init-tool.mjs";
 import { runSetupDetect } from "./setup-detect.mjs";
 
 const DEFAULT_SETUP_MANIFEST_PATH = ".clue/setup-manifest.json";
+const DEFAULT_ENV_GUIDE_PATH = ".env.clue";
+const BROWSER_INGEST_PATH = "/api/v1/ingest/browser";
+const BACKEND_INGEST_PATH = "/api/v1/ingest/backend";
 
 const writeJson = async ({ repoRoot, path, value }) => {
-	const absolutePath = join(resolve(repoRoot), path);
-	await mkdir(dirname(absolutePath), { recursive: true });
-	await writeFile(absolutePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+  const absolutePath = join(resolve(repoRoot), path);
+  await mkdir(dirname(absolutePath), { recursive: true });
+  await writeFile(absolutePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+};
+
+const writeText = async ({ repoRoot, path, value }) => {
+  const absolutePath = join(resolve(repoRoot), path);
+  await mkdir(dirname(absolutePath), { recursive: true });
+  await writeFile(absolutePath, value, "utf8");
 };
 
 const firstCandidateOrBlocker = (detection) => {
-	if (!detection.detected || detection.candidates.length === 0) {
-		return {
-			candidate: null,
-			blockers: detection.blockers.length
-				? detection.blockers
-				: [
-						{
-							code: "NO_SETUP_CANDIDATE",
-							message: "No setup candidate was mechanically detected.",
-						},
-					],
-		};
-	}
-	return {
-		candidate: detection.candidates[0],
-		blockers: [],
-	};
+  if (!detection.detected || detection.candidates.length === 0) {
+    return {
+      candidate: null,
+      blockers: detection.blockers.length
+        ? detection.blockers
+        : [
+            {
+              code: "NO_SETUP_CANDIDATE",
+              message: "No setup candidate was mechanically detected.",
+            },
+          ],
+    };
+  }
+  return {
+    candidate: detection.candidates[0],
+    blockers: [],
+  };
 };
 
 const DEFAULT_SETUP_LIFECYCLE = [
-	"init",
-	"identify",
-	"set-account",
-	"logout",
-	"event-sent",
+  "init",
+  "identify",
+  "set-account",
+  "logout",
+  "event-sent",
 ];
 
 const buildWatchTargets = (detection, fallbackCandidate) => {
-	const frontendServices = Array.isArray(detection.services?.frontend)
-		? detection.services.frontend
-		: [];
-	const backendServices = Array.isArray(detection.services?.backend)
-		? detection.services.backend
-		: [
-				{
-					kind: "backend",
-					framework: fallbackCandidate.framework,
-					root_path: fallbackCandidate.backend_root_path,
-					service_key: fallbackCandidate.service_key,
-					local_url_candidates: [],
-				},
-			];
-	return [...frontendServices, ...backendServices].map((service) => ({
-		kind: service.kind,
-		framework: service.framework,
-		root_path: service.root_path,
-		service_key: service.service_key,
-		producer_id: service.service_key,
-		expected_lifecycle: DEFAULT_SETUP_LIFECYCLE,
-		local_url_candidates: service.local_url_candidates ?? [],
-		url_env_name:
-			service.kind === "frontend"
-				? `CLUE_LOCAL_${service.service_key.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_FRONTEND_URL`
-				: `CLUE_LOCAL_${service.service_key.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_BACKEND_URL`,
-	}));
+  const frontendServices = Array.isArray(detection.services?.frontend)
+    ? detection.services.frontend
+    : [];
+  const backendServices = Array.isArray(detection.services?.backend)
+    ? detection.services.backend
+    : [
+        {
+          kind: "backend",
+          framework: fallbackCandidate.framework,
+          root_path: fallbackCandidate.backend_root_path,
+          service_key: fallbackCandidate.service_key,
+          local_url_candidates: [],
+        },
+      ];
+  return [...frontendServices, ...backendServices].map((service) => ({
+    kind: service.kind,
+    framework: service.framework,
+    root_path: service.root_path,
+    service_key: service.service_key,
+    producer_id: service.service_key,
+    expected_lifecycle: DEFAULT_SETUP_LIFECYCLE,
+    local_url_candidates: service.local_url_candidates ?? [],
+    url_env_name:
+      service.kind === "frontend"
+        ? `CLUE_LOCAL_${service.service_key.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_FRONTEND_URL`
+        : `CLUE_LOCAL_${service.service_key.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_BACKEND_URL`,
+  }));
+};
+
+const optionalString = (value) =>
+  typeof value === "string" && value.trim() ? value.trim() : null;
+
+const trimTrailingSlash = (value) => String(value).replace(/\/+$/, "");
+
+const buildEndpoint = (baseUrl, path) => `${trimTrailingSlash(baseUrl)}${path}`;
+
+const setupContextFromInput = (input = {}) => ({
+  clue_api_key: optionalString(input.clueApiKey),
+  clue_api_base_url: optionalString(input.clueApiBaseUrl),
+  project_key: optionalString(input.projectKey),
+  environment: optionalString(input.environment),
+});
+
+const envFileCandidates = (target) => {
+  if (target.kind === "frontend") {
+    return target.framework === "nextjs" ? [".env.local"] : [".env"];
+  }
+  return [".env"];
+};
+
+const buildServiceEnvBlock = ({ target, setupContext }) => {
+  const ingestPath =
+    target.kind === "frontend" ? BROWSER_INGEST_PATH : BACKEND_INGEST_PATH;
+  const variables = [
+    {
+      name: "CLUE_INGEST_ENDPOINT",
+      value: buildEndpoint(setupContext.clue_api_base_url, ingestPath),
+    },
+    { name: "CLUE_PROJECT_KEY", value: setupContext.project_key },
+    { name: "CLUE_ENVIRONMENT", value: setupContext.environment },
+    { name: "CLUE_SERVICE_KEY", value: target.service_key },
+  ];
+  if (target.kind === "backend") {
+    variables.push({ name: "CLUE_API_KEY", value: setupContext.clue_api_key });
+  }
+  return variables.map(({ name, value }) => `${name}=${value}`).join("\n");
+};
+
+const buildEnvironmentInstructions = ({ manifest, setupContext }) => {
+  const missingFlags = [
+    ["clue_api_key", "--clue-api-key"],
+    ["clue_api_base_url", "--clue-api-base-url"],
+    ["project_key", "--project-key"],
+    ["environment", "--environment"],
+  ]
+    .filter(([key]) => !setupContext[key])
+    .map(([, flag]) => flag);
+
+  if (missingFlags.length > 0 || manifest.status !== "ready_for_ai") {
+    return {
+      status: "missing_setup_arguments",
+      required_flags: missingFlags,
+      message:
+        "Run setup with Clue values from the setup screen to print service-specific env blocks.",
+    };
+  }
+
+  const watchTargets = manifest.lifecycle_verification.watch_targets;
+  return {
+    status: "ready",
+    env_file_path: DEFAULT_ENV_GUIDE_PATH,
+    message: "各サービスの env ファイルに以下を設定してください。",
+    service_env_blocks: watchTargets.map((target) => ({
+      kind: target.kind,
+      framework: target.framework,
+      root_path: target.root_path,
+      service_key: target.service_key,
+      env_file_candidates: envFileCandidates(target),
+      env_block: buildServiceEnvBlock({ target, setupContext }),
+    })),
+    ci_github: {
+      secrets: [
+        { name: "CLUE_API_KEY", value: setupContext.clue_api_key },
+        {
+          name: "CLUE_AI_PROVIDER_API_KEY",
+          value: "<openai-or-anthropic-api-key>",
+        },
+      ],
+      variables: [
+        { name: "CLUE_AI_PROVIDER", value: "<openai-or-anthropic>" },
+        { name: "CLUE_AI_MODEL", value: "<selected-provider-model>" },
+      ],
+    },
+  };
+};
+
+const buildEnvironmentGuideText = (instructions) => {
+  if (!instructions || instructions.status !== "ready") return null;
+  const lines = [
+    "# Clue setup environment values",
+    "# This file contains setup secrets. Do not commit it.",
+    "",
+    instructions.message,
+    "",
+  ];
+  for (const block of instructions.service_env_blocks) {
+    lines.push(
+      `[${block.kind}] ${block.root_path} (${block.env_file_candidates.join(" or ")})`,
+      block.env_block,
+      "",
+    );
+  }
+  lines.push(
+    "GitHub Secrets",
+    ...instructions.ci_github.secrets.map(
+      (entry) => `${entry.name}=${entry.value}`,
+    ),
+    "",
+  );
+  if (instructions.ci_github.variables.length > 0) {
+    lines.push(
+      "GitHub Variables",
+      ...instructions.ci_github.variables.map(
+        (entry) => `${entry.name}=${entry.value}`,
+      ),
+      "",
+    );
+  }
+  return `${lines.join("\n")}\n`;
+};
+
+const summarizeEnvironmentInstructions = (instructions) => {
+  if (!instructions || instructions.status !== "ready") {
+    return instructions;
+  }
+  return {
+    status: "ready",
+    env_file_path: instructions.env_file_path,
+    message:
+      `${instructions.env_file_path} を開き、各サービスの env と GitHub Secrets に反映してください。`,
+    service_env_block_count: instructions.service_env_blocks.length,
+    github_secret_names: instructions.ci_github.secrets.map(
+      (entry) => entry.name,
+    ),
+    github_variable_names: instructions.ci_github.variables.map(
+      (entry) => entry.name,
+    ),
+  };
+};
+
+const writeEnvironmentGuideIfReady = async ({ repoRoot, instructions }) => {
+  const content = buildEnvironmentGuideText(instructions);
+  if (!content) return null;
+  await writeText({
+    repoRoot,
+    path: instructions.env_file_path,
+    value: content,
+  });
+  return instructions.env_file_path;
 };
 
 export const runSetupPrepare = async ({
-	repoRoot,
-	target,
-	skillRoot,
-	setupManifestPath = DEFAULT_SETUP_MANIFEST_PATH,
+  repoRoot,
+  target,
+  skillRoot,
+  setupContext: setupContextInput,
+  setupManifestPath = DEFAULT_SETUP_MANIFEST_PATH,
 }) => {
-	const resolvedRepoRoot = resolve(repoRoot ?? ".");
-	const detection = await runSetupDetect({ repoRoot: resolvedRepoRoot });
-	const { candidate, blockers } = firstCandidateOrBlocker(detection);
-	if (!candidate) {
-		const manifest = {
-			status: "blocked",
-			target,
-			skill_root: skillRoot,
-			blockers,
-			detection,
-			ai_next_scope: "blocked_until_backend_routes_are_detected",
-			machine_owned_artifacts: [],
-			ai_owned_workstreams: [
-				"sdk_lifecycle_implementation_after_blockers_are_resolved",
-			],
-		};
-		await writeJson({
-			repoRoot: resolvedRepoRoot,
-			path: setupManifestPath,
-			value: manifest,
-		});
-		return manifest;
-	}
-
-	const request = buildSemanticWorkflowRequestFromFlags({
-		framework: candidate.framework,
-		backendRootPath: candidate.backend_root_path,
-		serviceKey: candidate.service_key,
-	});
-	const workflow = await writeSemanticWorkflow({
-		repoRoot: resolvedRepoRoot,
-		request,
-	});
-
-	const manifest = {
-		status: "ready_for_ai",
-		target,
-		skill_root: skillRoot,
-		detected: {
-			framework: candidate.framework,
-			backend_root_path: candidate.backend_root_path,
-			service_key: candidate.service_key,
-		},
-		service_identity: {
-			canonical_field: "service_key",
-			backend_env_name: "CLUE_SERVICE_KEY",
-			frontend_env_name: "NEXT_PUBLIC_CLUE_SERVICE_KEY",
-			producer_id_derivation: "producer_id defaults to service_key",
-		},
-		lifecycle_verification: {
-			watch_target_format:
-				"frontend:<service-key>[init,identify,set-account,logout,event-sent]=<frontend-url>,backend:<service-key>[init,identify,set-account,logout,event-sent]=<backend-url>",
-			rule:
-				"setup-watch --local uses the structured watch_targets below. Lifecycle checks are fixed for setup verification and are evaluated per service_key.",
-			watch_targets: buildWatchTargets(detection, candidate),
-		},
-		artifacts: {
-			ci_workflow_path: workflow.ci_workflow_path,
-			setup_manifest_path: setupManifestPath,
-			runtime_request_committed: false,
-		},
-		machine_owned_artifacts: [workflow.ci_workflow_path, setupManifestPath],
-		ai_must_not_edit: [workflow.ci_workflow_path],
-		ai_owned_workstreams: ["sdk_lifecycle_implementation"],
-		required_final_check: {
-			command:
-				`npx @clue-ai/cli setup-check --framework ${candidate.framework} ` +
-				`--backend-root-path ${candidate.backend_root_path} --repo . --target ${target} --require-sdk-lifecycle`,
-		},
-		required_env_names: [
-			"NEXT_PUBLIC_CLUE_SERVICE_KEY",
-			"NEXT_PUBLIC_CLUE_PROJECT_KEY",
-			"NEXT_PUBLIC_CLUE_ENVIRONMENT",
-			"NEXT_PUBLIC_CLUE_INGEST_ENDPOINT",
-			"CLUE_SERVICE_KEY",
-			"CLUE_API_KEY",
-			"AI_PROVIDER_API_KEY",
-			"CLUE_PROJECT_KEY",
-			"CLUE_ENVIRONMENT",
-			"CLUE_API_BASE_URL",
-			"CLUE_AI_MODEL",
-		],
-	};
-	await writeJson({
-		repoRoot: resolvedRepoRoot,
-		path: setupManifestPath,
-		value: manifest,
-	});
-	return manifest;
+  const resolvedRepoRoot = resolve(repoRoot ?? ".");
+  const setupContext = setupContextFromInput(setupContextInput);
+  const detection = await runSetupDetect({ repoRoot: resolvedRepoRoot });
+  const { candidate, blockers } = firstCandidateOrBlocker(detection);
+  if (!candidate) {
+    const manifest = {
+      status: "blocked",
+      target,
+      skill_root: skillRoot,
+      blockers,
+      detection,
+      ai_next_scope: "blocked_until_backend_routes_are_detected",
+      machine_owned_artifacts: [],
+      ai_owned_workstreams: [
+        "sdk_lifecycle_implementation_after_blockers_are_resolved",
+      ],
+    };
+    await writeJson({
+      repoRoot: resolvedRepoRoot,
+      path: setupManifestPath,
+      value: manifest,
+    });
+    const environmentInstructions = buildEnvironmentInstructions({
+      manifest,
+      setupContext,
+    });
+    return {
+      ...manifest,
+      environment_instructions:
+        summarizeEnvironmentInstructions(environmentInstructions),
+    };
+  }
+
+  const request = buildSemanticWorkflowRequestFromFlags({
+    framework: candidate.framework,
+    backendRootPath: candidate.backend_root_path,
+    serviceKey: candidate.service_key,
+    projectKey: setupContext.project_key,
+    environment: setupContext.environment,
+    clueApiBaseUrl: setupContext.clue_api_base_url,
+  });
+  const workflow = await writeSemanticWorkflow({
+    repoRoot: resolvedRepoRoot,
+    request,
+  });
+
+  const manifest = {
+    status: "ready_for_ai",
+    target,
+    skill_root: skillRoot,
+    detected: {
+      framework: candidate.framework,
+      backend_root_path: candidate.backend_root_path,
+      service_key: candidate.service_key,
+    },
+    service_identity: {
+      canonical_field: "service_key",
+      backend_env_name: "CLUE_SERVICE_KEY",
+      frontend_env_name: "CLUE_SERVICE_KEY",
+      producer_id_derivation: "producer_id defaults to service_key",
+    },
+    clue_context: {
+      project_key: setupContext.project_key,
+      environment: setupContext.environment,
+      clue_api_base_url: setupContext.clue_api_base_url,
+      ingest_endpoints: setupContext.clue_api_base_url
+        ? {
+            browser: buildEndpoint(
+              setupContext.clue_api_base_url,
+              BROWSER_INGEST_PATH,
+            ),
+            backend: buildEndpoint(
+              setupContext.clue_api_base_url,
+              BACKEND_INGEST_PATH,
+            ),
+          }
+        : null,
+    },
+    lifecycle_verification: {
+      watch_target_format:
+        "frontend:<service-key>[init,identify,set-account,logout,event-sent]=<frontend-url>,backend:<service-key>[init,identify,set-account,logout,event-sent]=<backend-url>",
+      rule: "setup-watch --local uses the structured watch_targets below. Lifecycle checks are fixed for setup verification and are evaluated per service_key.",
+      watch_targets: buildWatchTargets(detection, candidate),
+    },
+    artifacts: {
+      ci_workflow_path: workflow.ci_workflow_path,
+      setup_manifest_path: setupManifestPath,
+      runtime_request_committed: false,
+    },
+    machine_owned_artifacts: [workflow.ci_workflow_path, setupManifestPath],
+    ai_must_not_edit: [workflow.ci_workflow_path],
+    ai_owned_workstreams: ["sdk_lifecycle_implementation"],
+    required_final_check: {
+      command:
+        `npx @clue-ai/cli setup-check --framework ${candidate.framework} ` +
+        `--backend-root-path ${candidate.backend_root_path} --repo . --target ${target} --require-sdk-lifecycle`,
+    },
+    required_env_names: [
+      "CLUE_SERVICE_KEY",
+      "CLUE_API_KEY",
+      "CLUE_AI_PROVIDER",
+      "CLUE_AI_PROVIDER_API_KEY",
+      "CLUE_AI_MODEL",
+      "CLUE_PROJECT_KEY",
+      "CLUE_ENVIRONMENT",
+      "CLUE_INGEST_ENDPOINT",
+      "CLUE_API_BASE_URL",
+    ],
+  };
+  const environmentInstructions = buildEnvironmentInstructions({
+    manifest,
+    setupContext,
+  });
+  const manifestWithEnvironmentArtifact = {
+    ...manifest,
+    artifacts: {
+      ...manifest.artifacts,
+      environment_file_path:
+        environmentInstructions.status === "ready"
+          ? environmentInstructions.env_file_path
+          : null,
+    },
+  };
+  await writeJson({
+    repoRoot: resolvedRepoRoot,
+    path: setupManifestPath,
+    value: manifestWithEnvironmentArtifact,
+  });
+  const environmentFilePath = await writeEnvironmentGuideIfReady({
+    repoRoot: resolvedRepoRoot,
+    instructions: environmentInstructions,
+  });
+  return {
+    ...manifestWithEnvironmentArtifact,
+    artifacts: {
+      ...manifestWithEnvironmentArtifact.artifacts,
+      environment_file_path: environmentFilePath,
+    },
+    environment_instructions:
+      summarizeEnvironmentInstructions(environmentInstructions),
+  };
 };