@genn-inc/cluebase-cli 0.0.1

package/src/setup-help.mjs

@@ -0,0 +1,130 @@
+import {
+  CLUEBASE_CLI_INVOCATION_CONTRACT,
+  cluebaseCliCommand,
+} from "./cli-invocation.mjs";
+import {
+  AI_SETUP_CONTRACT_VERSION,
+  API_CONNECTIVITY_CONTRACT,
+  DETERMINISTIC_CONTROL_MODEL,
+  FRONTEND_ADAPTER_CONTRACT,
+  GROUP_BOUNDARY_CONTRACT,
+  IDENTITY_BOUNDARY_CONTRACT,
+  OTEL_FIRST_SETUP_CONTRACT,
+  SETUP_DOCTRINE,
+} from "./setup-ai-contract.mjs";
+import {
+  buildSetupDocumentationContract,
+  EXTERNAL_DATA_CONNECTION_PATH,
+  EXTERNAL_DATA_CONNECTION_SCREEN_NAME,
+} from "./setup-documents.mjs";
+export const AI_SETUP_HELP_VERSION = AI_SETUP_CONTRACT_VERSION;
+
+export const buildAiSetupHelp = () => ({
+  name: "@genn-inc/cluebase-cli AI setup help",
+  version: AI_SETUP_HELP_VERSION,
+  purpose:
+    "Machine-readable Cluebase setup contract for AI coding agents. Use this before editing a customer repository for Cluebase setup.",
+  cli_invocation: CLUEBASE_CLI_INVOCATION_CONTRACT,
+  setup_execution_contract: {
+    setup_doctrine: SETUP_DOCTRINE,
+    deterministic_control_model: DETERMINISTIC_CONTROL_MODEL,
+    api_connectivity_contract: API_CONNECTIVITY_CONTRACT,
+    frontend_adapter_contract: FRONTEND_ADAPTER_CONTRACT,
+    identity_boundary_contract: IDENTITY_BOUNDARY_CONTRACT,
+    group_boundary_contract: GROUP_BOUNDARY_CONTRACT,
+    otel_first_setup_contract: OTEL_FIRST_SETUP_CONTRACT,
+    agent_primary_task:
+      "Decide where to place cluebase.init, cluebase.identify, cluebase.group, and cluebase.reset in existing repository lifecycle boundaries, then apply only those minimal Cluebase SDK wiring changes.",
+    implementation_workstreams: ["sdk_lifecycle_placement"],
+    lifecycle_apis_in_scope: [
+      "cluebase.init",
+      "cluebase.identify",
+      "cluebase.group",
+      "cluebase.reset",
+    ],
+    lifecycle_apis_out_of_scope_by_default: ["cluebase.track"],
+    allowed_change_scope: {
+      rule: "Only exact changes required to place cluebase.init, cluebase.identify, cluebase.group, and cluebase.reset are allowed.",
+      allowed: [
+        "Cluebase SDK dependency declarations and lockfile changes needed to install those SDKs",
+        "Cluebase SDK imports, bootstrap adapters, and single initialization points",
+        "Cluebase lifecycle calls at existing clear login, logout, company, organization, or tenant boundaries",
+        "tests or verification scripts directly proving the four lifecycle API placement decisions",
+      ],
+      forbidden: [
+        "cluebase.track instrumentation unless the user explicitly requested product event tracking",
+        "unrelated refactors, renames, file moves, formatting churn, or broad cleanup",
+        "business logic changes that are not required for Cluebase setup",
+        "auth/session flow rewrites beyond the minimal Cluebase hook insertion point",
+        "default cluebase.identify insertion in token refresh, current-user sync, session polling, request exchange, read hook, or repeated helper paths unless repository evidence proves that path is the one-time auth success boundary",
+        "UI layout, styling, copy, or navigation changes unrelated to Cluebase setup",
+        "dependency upgrades unrelated to Cluebase SDK installability",
+        "whitespace-only edits, import sorting, formatter churn, or comment/style cleanup outside the exact Cluebase SDK wiring lines",
+      ],
+    },
+    instrumentation_contract: {
+      rule:
+        "OpenTelemetry/OpenLLMetry/GenAI semantic instrumentation is primary wherever available; Cluebase helpers are enrichment/fallback only.",
+      details: OTEL_FIRST_SETUP_CONTRACT.rules,
+    },
+    sdk_dependency_contract: {
+      frontend: {
+        package: "@genn-inc/cluebase-frontend-sdk",
+        install: "package-manager add @genn-inc/cluebase-frontend-sdk@latest",
+        rule:
+          "Frontend package.json must declare @genn-inc/cluebase-frontend-sdk. The dependency version and lockfile resolution are not part of lifecycle verification.",
+      },
+      backend: {
+        fastapi_package: "cluebase-backend-sdk",
+        django_package: "cluebase-backend-sdk",
+        install: "pip install cluebase-backend-sdk",
+        rule:
+          "Python backend SDK dependency declarations must include cluebase-backend-sdk. The dependency version is not part of lifecycle verification.",
+        node_package: "@genn-inc/cluebase-backend-sdk",
+        node_install: "package-manager add @genn-inc/cluebase-backend-sdk",
+        node_rule:
+          "Node backend SDK dependency declarations must include @genn-inc/cluebase-backend-sdk. The dependency version is not part of lifecycle verification.",
+      },
+    },
+    environment_contract: {
+      nextjs_frontend_client_env: {
+        variables: [
+          "NEXT_PUBLIC_CLUEBASE_PROJECT_KEY",
+          "NEXT_PUBLIC_CLUEBASE_API_BASE_URL",
+        ],
+        rule: "NEXT_PUBLIC_* is the Next.js browser/client env contract only. For non-Next.js frontend frameworks, use the framework-specific public env names generated by Cluebase setup. Browser token issuance uses the Cluebase API base URL, projectKey, and request Origin.",
+      },
+    },
+    documentation_contract: buildSetupDocumentationContract(),
+    external_data_source_contract: {
+      screen_name: EXTERNAL_DATA_CONNECTION_SCREEN_NAME,
+      screen_path: EXTERNAL_DATA_CONNECTION_PATH,
+      rule:
+        "Value data that no SDK call can capture — because it lives only in an external system the customer app never sees (a billing platform, a CRM, a spreadsheet, an analytics export) — is ingested by connecting that system on the Cluebase external data connection screen, not by fabricating a cluebase.track call. During guided business-event instrumentation, milestones with no authoritative in-repo code path are recorded as external_source_only and the customer is pointed at this screen.",
+      customer_navigation:
+        "Cluebase web app sidebar Settings → 外部データ, at " +
+        EXTERNAL_DATA_CONNECTION_PATH,
+    },
+    setup_verification: {
+      owner: "ai_or_user",
+      ai_agent_may_run: true,
+      command: cluebaseCliCommand("setup-doctor --local"),
+      rule: "Run setup-doctor after local frontend/backend services and required env are available. Missing inputs are reported as skipped/pending; real connectivity failures block verified completion unless setup-doctor is explicitly skipped. It checks API connectivity plus downstream published batch status before the user verifies real product-flow logs.",
+      checked_hops: Object.keys(API_CONNECTIVITY_CONTRACT.hops),
+    },
+    completion_boundary: {
+      ai_may_claim: [
+        "Cluebase setup code changes were applied",
+        "static setup-check passed",
+        "SDK dependency install/import/build/typecheck checks passed when actually run",
+      ],
+      ai_must_not_claim: [
+        "setup completed",
+        "event delivery verified",
+        "Cluebase setup screen verification passed",
+      ],
+      final_status_when_real_flow_not_user_verified:
+        "user_verification_pending",
+    },
+  },
+});

package/src/setup-prepare.mjs

@@ -0,0 +1,360 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import {
+  CLUEBASE_CLI_INVOCATION_CONTRACT,
+  cluebaseCliCommand,
+} from "./cli-invocation.mjs";
+import {
+  API_CONNECTIVITY_CONTRACT,
+  IDENTITY_BOUNDARY_CONTRACT,
+  OTEL_FIRST_SETUP_CONTRACT,
+} from "./setup-ai-contract.mjs";
+import { buildSetupDocumentationContract } from "./setup-documents.mjs";
+import { discoverSetupRepository } from "./setup-repository-discovery.mjs";
+
+const DEFAULT_SETUP_MANIFEST_PATH = ".cluebase/setup-manifest.json";
+const BROWSER_INGEST_PATH =
+  API_CONNECTIVITY_CONTRACT.hops.browser_ingest.path;
+const BACKEND_INGEST_PATH = "/api/v1/ingest/backend";
+// setup runtime で各 service が読む env 名一覧。
+// 実際の値の提示は setup 画面 (web app の setup wizard) が担当する。
+// CLI はサービス検出と manifest 出力のみを担う。
+const FRONTEND_PUBLIC_ENV_NAMES = [
+  "CLUEBASE_API_BASE_URL",
+  "CLUEBASE_PROJECT_KEY",
+];
+const FRONTEND_PUBLIC_ENV_PREFIX_BY_FRAMEWORK = new Map([
+  ["nextjs", "NEXT_PUBLIC_"],
+  ["vite", "VITE_"],
+  ["vue", "VITE_"],
+  ["react", "REACT_APP_"],
+  ["sveltekit", "PUBLIC_"],
+  ["nuxt", "NUXT_PUBLIC_"],
+]);
+const BACKEND_RUNTIME_ENV_NAMES = [
+  "CLUEBASE_PROJECT_KEY",
+  "CLUEBASE_INGEST_ENDPOINT",
+  "CLUEBASE_API_KEY",
+];
+
+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 buildDetectedServices = (detection) => {
+  const frontendServices = Array.isArray(detection.services?.frontend)
+    ? detection.services.frontend
+    : [];
+  const backendServices = Array.isArray(detection.services?.backend)
+    ? detection.services.backend
+    : [];
+  return [...frontendServices, ...backendServices].map((service) => {
+    const targetId =
+      service.kind === "frontend" ? service.target_id : service.service_key;
+    if (typeof targetId !== "string" || !targetId.trim()) {
+      throw new Error("setup service target_id is required");
+    }
+    const targetIdForEnv = targetId.trim();
+    return {
+      kind: service.kind,
+      framework: service.framework,
+      root_path: service.root_path,
+      target_id: targetIdForEnv,
+      local_url_candidates: service.local_url_candidates ?? [],
+    };
+  });
+};
+
+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 = {}) => {
+  const projectKey = optionalString(input.projectKey);
+  return {
+    cluebase_api_key: optionalString(input.cluebaseApiKey),
+    cluebase_api_base_url: optionalString(input.cluebaseApiBaseUrl),
+    documents_url: optionalString(input.documentsUrl),
+    project_key: projectKey,
+  };
+};
+
+const frontendEnvName = ({ target, name }) => {
+  if (target.kind !== "frontend") return null;
+  const prefix = FRONTEND_PUBLIC_ENV_PREFIX_BY_FRAMEWORK.get(
+    String(target.framework ?? "").toLowerCase(),
+  );
+  return prefix === undefined ? null : `${prefix}${name}`;
+};
+
+const requiredFrontendEnvNames = (detectedServices) => [
+  ...new Set(
+    detectedServices
+      .filter((target) => target.kind === "frontend")
+      .flatMap((target) =>
+        FRONTEND_PUBLIC_ENV_NAMES.map((name) =>
+          frontendEnvName({ target, name }),
+        ),
+      )
+      .filter(Boolean),
+  ),
+];
+
+const requiredBackendEnvNames = () => [...BACKEND_RUNTIME_ENV_NAMES];
+
+// 環境変数は CLI 側で .env.cluebase ファイルを生成せず、setup 画面 (web app の setup wizard)
+// に表示・誘導を任せる方針。 CLI はサービス検出結果と manifest 出力だけを担う。
+// この関数は CLI が detect した service 一覧と「Step 2 は setup 画面で行ってください」
+// という deferred 状態を返すのみ。
+const buildEnvironmentInstructions = ({ manifest, setupContext }) => {
+  const missingFlags = [
+    ["cluebase_api_key", "--cluebase-api-key"],
+    ["cluebase_api_base_url", "--cluebase-api-base-url"],
+    ["project_key", "--project-key"],
+  ]
+    .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 Cluebase values from the setup screen to view target-specific env blocks.",
+    };
+  }
+
+  const detectedServices = Array.isArray(manifest.detected_services)
+    ? manifest.detected_services
+    : [];
+  return {
+    status: "deferred_to_setup_wizard",
+    message:
+      "環境変数は setup 画面の Step 2 を見て、各サービスの env ファイルに反映してください。",
+    detected_services: detectedServices.map((target) => ({
+      kind: target.kind,
+      framework: target.framework,
+      root_path: target.root_path,
+    })),
+  };
+};
+
+const summarizeEnvironmentInstructions = (instructions) => {
+  if (!instructions || instructions.status !== "deferred_to_setup_wizard") {
+    return instructions;
+  }
+  return {
+    status: "deferred_to_setup_wizard",
+    message: instructions.message,
+    detected_services: instructions.detected_services,
+  };
+};
+
+export const runSetupPrepare = async ({
+  repoRoot,
+  setupContext: setupContextInput,
+  setupManifestPath = DEFAULT_SETUP_MANIFEST_PATH,
+}) => {
+  const resolvedRepoRoot = resolve(repoRoot ?? ".");
+  const setupContext = setupContextFromInput(setupContextInput);
+  const detection = await discoverSetupRepository({ repoRoot: resolvedRepoRoot });
+  if (!detection.detected) {
+    const manifest = {
+      status: "blocked",
+      documentation: buildSetupDocumentationContract({
+        documentsUrl: setupContext.documents_url,
+        frameworks: [],
+      }),
+      blockers: detection.blockers,
+      detection,
+      ai_next_scope: "blocked_until_an_instrumentable_service_is_detected",
+      machine_owned_artifacts: [],
+      ai_owned_workstreams: [
+        "sdk_lifecycle_placement_after_blockers_are_resolved",
+      ],
+      ai_implementation_scope: {
+        rule: "AI implementation is limited to placing cluebase.init, cluebase.identify, cluebase.group, and cluebase.reset in existing lifecycle boundaries after blockers are resolved.",
+        lifecycle_apis: [
+          "cluebase.init",
+          "cluebase.identify",
+          "cluebase.group",
+          "cluebase.reset",
+        ],
+        out_of_scope_by_default: ["cluebase.track"],
+        identity_boundary_contract: IDENTITY_BOUNDARY_CONTRACT,
+        instrumentation_contract: OTEL_FIRST_SETUP_CONTRACT,
+      },
+    };
+    await writeJson({
+      repoRoot: resolvedRepoRoot,
+      path: setupManifestPath,
+      value: manifest,
+    });
+    const environmentInstructions = buildEnvironmentInstructions({
+      manifest,
+      setupContext,
+    });
+    return {
+      ...manifest,
+      environment_instructions: summarizeEnvironmentInstructions(
+        environmentInstructions,
+      ),
+    };
+  }
+
+  const candidate = detection.candidates[0] ?? null;
+  const backendExists = detection.services.backend.length > 0;
+  const detectedServices = buildDetectedServices(detection);
+  const primaryFramework =
+    candidate?.framework ??
+    detection.services.frontend[0]?.framework ??
+    null;
+  const detectedFrameworks = [
+    ...(candidate ? [candidate.framework] : []),
+    ...detectedServices.map((target) => target.framework),
+  ];
+  const frontendRuntimeEnvNames = requiredFrontendEnvNames(detectedServices);
+  const backendRuntimeEnvNames = backendExists ? requiredBackendEnvNames() : [];
+  const serviceRuntimeEnvNames = [
+    ...new Set([...frontendRuntimeEnvNames, ...backendRuntimeEnvNames]),
+  ];
+  const finalSetupCheckCommand = candidate
+    ? cluebaseCliCommand(
+        `setup-check --framework ${candidate.framework} ` +
+          `--backend-root-path ${candidate.backend_root_path} --repo . --require-sdk-lifecycle`,
+      )
+    : cluebaseCliCommand("setup-check --repo . --require-sdk-lifecycle");
+
+  const manifest = {
+    status: "ready_for_ai",
+    detected: {
+      framework: primaryFramework,
+      ...(candidate
+        ? {
+            backend_root_path: candidate.backend_root_path,
+            service_key: candidate.service_key,
+          }
+        : {}),
+    },
+    documentation: buildSetupDocumentationContract({
+      documentsUrl: setupContext.documents_url,
+      framework: primaryFramework,
+      frameworks: detectedFrameworks,
+    }),
+    cli_invocation: CLUEBASE_CLI_INVOCATION_CONTRACT,
+    cluebase_context: {
+      project_key: setupContext.project_key,
+      cluebase_api_base_url: setupContext.cluebase_api_base_url,
+      api_connectivity_contract: API_CONNECTIVITY_CONTRACT,
+      ingest_endpoints: setupContext.cluebase_api_base_url
+        ? {
+            browser: buildEndpoint(
+              setupContext.cluebase_api_base_url,
+              BROWSER_INGEST_PATH,
+            ),
+            backend: buildEndpoint(
+              setupContext.cluebase_api_base_url,
+              BACKEND_INGEST_PATH,
+            ),
+          }
+        : null,
+    },
+    detected_services: detectedServices,
+    lifecycle_verification: {
+      owner: "user",
+      rule: "After setup-doctor passes, run the local customer frontend/backend, perform the real product flow, and verify the resulting Cluebase logs in the setup screen or published batch evidence.",
+    },
+    artifacts: {
+      setup_manifest_path: setupManifestPath,
+    },
+    machine_owned_artifacts: [setupManifestPath],
+    ai_must_not_edit: [],
+    ai_owned_workstreams: ["sdk_lifecycle_placement"],
+    ai_implementation_scope: {
+      rule: "AI implementation is limited to placing cluebase.init, cluebase.identify, cluebase.group, and cluebase.reset in existing lifecycle boundaries plus the minimal SDK wiring required for those calls.",
+      lifecycle_apis: [
+        "cluebase.init",
+        "cluebase.identify",
+        "cluebase.group",
+        "cluebase.reset",
+      ],
+      out_of_scope_by_default: ["cluebase.track"],
+      identity_boundary_contract: IDENTITY_BOUNDARY_CONTRACT,
+      instrumentation_contract: OTEL_FIRST_SETUP_CONTRACT,
+    },
+    required_final_check: {
+      command: finalSetupCheckCommand,
+    },
+    required_final_verification: [
+      {
+        id: "static_setup_check",
+        command: finalSetupCheckCommand,
+        completion_meaning:
+          "static_passed_only_dependency_install_import_app_startup_and_event_delivery_still_required",
+      },
+      {
+        id: "sdk_dependency_install_and_import",
+        command:
+          "run the repository package-manager install plus frontend/backend SDK import checks in the target environments",
+        completion_meaning:
+          "required before claiming SDK lifecycle setup is complete",
+      },
+      {
+        id: "app_startup",
+        command:
+          "start the affected frontend/backend services and verify their configured local URLs respond",
+        completion_meaning:
+          "required before real product-flow event delivery can be trusted",
+      },
+      {
+        id: "local_api_connectivity_preflight",
+        command: cluebaseCliCommand("setup-doctor --local"),
+        completion_meaning:
+          "required before real product-flow verification; verifies direct browser-token issuance, canonical browser observation-source-event batch ingest, and backend ingest connectivity when local services and required env are available",
+      },
+      {
+        id: "local_event_delivery",
+        command:
+          "user runs the local customer frontend/backend, performs the real product flow, and checks Cluebase setup logs or published batch evidence",
+        completion_meaning:
+          "requires user-operated local services plus expected lifecycle event delivery; AI agents must report user_verification_pending when user evidence is not provided",
+      },
+    ],
+    // server / SDK は project_key の prefix (pk_dev_ / pk_prod_) から
+    // environment を derive する。
+    required_env_names: [
+      ...new Set([
+        ...serviceRuntimeEnvNames,
+        ...(backendExists ? ["CLUEBASE_API_KEY"] : []),
+        "CLUEBASE_PROJECT_KEY",
+        "CLUEBASE_API_BASE_URL",
+      ]),
+    ],
+    required_env_scopes: {
+      service_runtime: serviceRuntimeEnvNames,
+      frontend_runtime: frontendRuntimeEnvNames,
+      backend_runtime: backendRuntimeEnvNames,
+    },
+  };
+  const environmentInstructions = buildEnvironmentInstructions({
+    manifest,
+    setupContext,
+  });
+  await writeJson({
+    repoRoot: resolvedRepoRoot,
+    path: setupManifestPath,
+    value: manifest,
+  });
+  return {
+    ...manifest,
+    environment_instructions: summarizeEnvironmentInstructions(
+      environmentInstructions,
+    ),
+  };
+};