@clue-ai/cli 0.0.3

package/README.md

@@ -0,0 +1,30 @@
+# Clue Tool
+
+This repository owns the Codex / Claude Code SDK init tool and the client-side CI semantic generation runner.
+
+The Clue product repository keeps SDKs, shared schemas, and API contracts. Tool implementation lives here so client repositories do not receive tool source code and the product repository does not become the tool runtime.
+
+## Commands
+
+```bash
+/clue-init
+clue-ai init --request clue-init-request.json --repo .
+clue-ai semantic-ci --request clue-semantic-request.json --repo .
+```
+
+`/clue-init` is the standard user-facing command for Codex and Claude Code
+wrappers. The command collects structured setup inputs and invokes the same
+tool request/report contract as `clue-ai init`.
+
+## Required Secrets
+
+- `CLUE_API_KEY`
+- `AI_PROVIDER_API_KEY`
+
+## Boundaries
+
+- The tool may read allowed source paths in the client repository.
+- The tool must not read `.env`, secrets, logs, dumps, build output, or vendor directories.
+- Raw source code is sent only from the client CI runner to the configured AI provider.
+- Raw source code, raw SQL, bind values, function names, class names, file paths, and import graphs are not sent to Clue by default.
+- `clue-layer.yaml` and `clue-semantic.yaml` are not committed to client repositories.

package/bin/clue-tool.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { commandSpecs } from "../src/command-spec.mjs";
+import { runInitTool } from "../src/init-tool.mjs";
+import { runSemanticCi } from "../src/semantic-ci.mjs";
+import { installSetupSkills } from "../src/setup-tool.mjs";
+
+const parseArgs = (argv) => {
+  const [command = "help", ...tokens] = argv;
+  const flags = new Map();
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (!token.startsWith("--")) continue;
+    const key = token.slice(2);
+    const next = tokens[index + 1];
+    if (next && !next.startsWith("--")) {
+      flags.set(key, next);
+      index += 1;
+    } else {
+      flags.set(key, true);
+    }
+  }
+  return { command, flags };
+};
+
+const readJson = async (path) => JSON.parse(await readFile(path, "utf8"));
+
+const usage = () => [
+  "Usage:",
+  "  /clue-init",
+  "  clue-ai setup",
+  "  clue-ai init --request clue-init-request.json --repo .",
+  "  clue-ai semantic-ci --request clue-semantic-request.json --repo .",
+].join("\n");
+
+const main = async () => {
+  const { command, flags } = parseArgs(process.argv.slice(2));
+  if (command === "help" || flags.has("help")) {
+    process.stdout.write(`${usage()}\n`);
+    return;
+  }
+
+  if (command === "commands") {
+    process.stdout.write(`${JSON.stringify({ commands: commandSpecs }, null, 2)}\n`);
+    return;
+  }
+
+  const requestPath = flags.get("request");
+  const repoRoot = resolve(String(flags.get("repo") || "."));
+  if (command === "setup") {
+    const report = await installSetupSkills({
+      repoRoot,
+      target: typeof flags.get("target") === "string" ? flags.get("target") : undefined,
+    });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+
+  if (typeof requestPath !== "string") {
+    throw new Error("--request is required");
+  }
+  const request = await readJson(resolve(requestPath));
+
+  if (command === "init") {
+    const report = await runInitTool({ repoRoot, request });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+
+  if (command === "semantic-ci") {
+    const result = await runSemanticCi({ repoRoot, request, env: process.env });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}\n${usage()}`);
+};
+
+main().catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+});

package/commands/claude-code/clue-init.md

@@ -0,0 +1,27 @@
+# /clue-init
+
+Run the Clue SDK initialization tool with structured inputs.
+
+Required fields:
+
+- `project_key`
+- `service_key`
+- `framework`
+- `backend_root_path`
+- `environment`
+- `allowed_source_paths`
+- `excluded_source_paths`
+
+Required secrets:
+
+- `CLUE_API_KEY`
+- `AI_PROVIDER_API_KEY`
+
+Behavior:
+
+1. Collect the required fields as structured input.
+2. Build the canonical init request.
+3. Run `clue-ai init --request <generated-request.json> --repo .`.
+4. Show the generated report and low-confidence review points.
+
+Do not ask the user to write a free-form setup prompt.

package/commands/codex/clue-init.md

@@ -0,0 +1,27 @@
+# /clue-init
+
+Run the Clue SDK initialization tool with structured inputs.
+
+Required fields:
+
+- `project_key`
+- `service_key`
+- `framework`
+- `backend_root_path`
+- `environment`
+- `allowed_source_paths`
+- `excluded_source_paths`
+
+Required secrets:
+
+- `CLUE_API_KEY`
+- `AI_PROVIDER_API_KEY`
+
+Behavior:
+
+1. Collect the required fields as structured input.
+2. Build the canonical init request.
+3. Run `clue-ai init --request <generated-request.json> --repo .`.
+4. Show the generated report and low-confidence review points.
+
+Do not ask the user to write a free-form setup prompt.

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@clue-ai/cli",
+  "version": "0.0.3",
+  "type": "module",
+  "bin": {
+    "clue-ai": "bin/clue-tool.mjs"
+  },
+  "files": [
+    "bin/",
+    "commands/",
+    "src/",
+    "README.md"
+  ],
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/command-spec.mjs

@@ -0,0 +1,73 @@
+export const CLUE_INIT_COMMAND_NAME = "/clue-init";
+
+export const REQUIRED_SECRET_NAMES = [
+  "CLUE_API_KEY",
+  "AI_PROVIDER_API_KEY",
+];
+
+export const CLUE_INIT_COMMAND_FIELDS = [
+  "project_key",
+  "service_key",
+  "framework",
+  "backend_root_path",
+  "environment",
+  "allowed_source_paths",
+  "excluded_source_paths",
+];
+
+export const CLUE_INIT_COMMAND = {
+  name: CLUE_INIT_COMMAND_NAME,
+  description: "Initialize Clue SDK lifecycle capture and semantic CI.",
+  supported_tools: ["codex", "claude_code"],
+  request_contract: "clueInitToolRequestSchema",
+  report_contract: "clueInitToolReportSchema",
+  required_fields: CLUE_INIT_COMMAND_FIELDS,
+  required_secret_names: REQUIRED_SECRET_NAMES,
+};
+
+export const commandSpecs = [CLUE_INIT_COMMAND];
+
+const requireField = (input, field) => {
+  const value = input?.[field];
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${field} is required for ${CLUE_INIT_COMMAND_NAME}`);
+  }
+  return value.trim();
+};
+
+const normalizeStringArray = (value, fallback, field) => {
+  const source = value === undefined ? fallback : value;
+  if (!Array.isArray(source)) {
+    throw new Error(`${field} must be an array for ${CLUE_INIT_COMMAND_NAME}`);
+  }
+  return source
+    .filter((entry) => typeof entry === "string" && entry.trim())
+    .map((entry) => entry.trim());
+};
+
+export const buildClueInitRequestFromCommandInput = ({
+  targetTool,
+  input,
+}) => {
+  const backendRootPath = requireField(input, "backend_root_path");
+  return {
+    target_tool: targetTool,
+    project_key: requireField(input, "project_key"),
+    service_key: requireField(input, "service_key"),
+    framework: requireField(input, "framework"),
+    environment: requireField(input, "environment"),
+    allowed_source_paths: normalizeStringArray(
+      input?.allowed_source_paths,
+      [backendRootPath],
+      "allowed_source_paths",
+    ),
+    excluded_source_paths: normalizeStringArray(
+      input?.excluded_source_paths,
+      [],
+      "excluded_source_paths",
+    ),
+    ...(typeof input?.ci_workflow_path === "string" && input.ci_workflow_path.trim()
+      ? { ci_workflow_path: input.ci_workflow_path.trim() }
+      : {}),
+  };
+};

package/src/contracts.mjs

@@ -0,0 +1,124 @@
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const schemaPackage = require("./public-schema.cjs");
+
+const {
+  clueInitToolRequestSchema,
+  clueInitToolReportSchema,
+  semanticSnapshotRequestSchema,
+} = schemaPackage;
+
+const formatSchemaError = (result, field) => {
+  const issues = result.error.issues.map((issue) => {
+    const path = issue.path.length ? issue.path.join(".") : field;
+    return `${path}: ${issue.message}`;
+  });
+  return `${field} is invalid: ${issues.join("; ")}`;
+};
+
+const parseWithSchema = (schema, input, field) => {
+  const result = schema.safeParse(input);
+  if (!result.success) {
+    throw new Error(formatSchemaError(result, field));
+  }
+  return result.data;
+};
+
+const nonEmpty = (value, field) => {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${field} is required`);
+  }
+  return value.trim();
+};
+
+const optionalNonEmpty = (value) =>
+  typeof value === "string" && value.trim() ? value.trim() : null;
+
+const stringArray = (value, field, { min = 0 } = {}) => {
+  if (!Array.isArray(value)) {
+    throw new Error(`${field} must be an array`);
+  }
+  const result = value.map((entry) => nonEmpty(entry, field));
+  if (result.length < min) {
+    throw new Error(`${field} must include at least ${min} item(s)`);
+  }
+  return [...new Set(result)];
+};
+
+export const validateInitRequest = (input) => {
+  const parsed = parseWithSchema(clueInitToolRequestSchema, input, "init request");
+  return {
+    ...parsed,
+    allowed_source_paths: [...new Set(parsed.allowed_source_paths)],
+    excluded_source_paths: [...new Set(parsed.excluded_source_paths ?? [])],
+  };
+};
+
+export const buildInitReport = ({ request, lifecycleInsertions, warnings = [] }) =>
+  parseWithSchema(
+    clueInitToolReportSchema,
+    {
+      target_tool: request.target_tool,
+      ci_workflow_path: request.ci_workflow_path,
+      ci_workflow_added: true,
+      required_secrets: ["CLUE_API_KEY", "AI_PROVIDER_API_KEY"],
+      lifecycle_insertions: lifecycleInsertions,
+      semantic_generation_timing: "after_merge_ci",
+      semantic_preview_generated: false,
+      client_repo_generated_files_committed: false,
+      clue_track_inserted: false,
+      clue_dom_tag_inserted: false,
+      allowed_source_paths: request.allowed_source_paths,
+      excluded_source_paths: request.excluded_source_paths,
+      warnings,
+    },
+    "init report",
+  );
+
+export const validateSemanticCiRequest = (input) => ({
+  project_key: nonEmpty(input.project_key, "project_key"),
+  environment: nonEmpty(input.environment, "environment"),
+  service_key: nonEmpty(input.service_key, "service_key"),
+  repository: {
+    provider: nonEmpty(input.repository?.provider, "repository.provider"),
+    repository_id: nonEmpty(input.repository?.repository_id, "repository.repository_id"),
+    ...(optionalNonEmpty(input.repository?.owner)
+      ? { owner: optionalNonEmpty(input.repository.owner) }
+      : {}),
+    ...(optionalNonEmpty(input.repository?.name)
+      ? { name: optionalNonEmpty(input.repository.name) }
+      : {}),
+    ...(optionalNonEmpty(input.repository?.default_branch)
+      ? { default_branch: optionalNonEmpty(input.repository.default_branch) }
+      : {}),
+    merge_commit: nonEmpty(input.repository?.merge_commit, "repository.merge_commit"),
+    ...(optionalNonEmpty(input.repository?.merged_at)
+      ? { merged_at: optionalNonEmpty(input.repository.merged_at) }
+      : {}),
+    ...(input.repository?.pull_request_number === undefined || input.repository?.pull_request_number === null
+      ? {}
+      : { pull_request_number: input.repository.pull_request_number }),
+    ...(optionalNonEmpty(input.repository?.workflow_run_id)
+      ? { workflow_run_id: optionalNonEmpty(input.repository.workflow_run_id) }
+      : {}),
+  },
+  service: {
+    service_key: nonEmpty(input.service?.service_key ?? input.service_key, "service.service_key"),
+    root_path: input.service?.root_path ?? null,
+    framework: input.service?.framework ?? "fastapi",
+    language: input.service?.language ?? "python",
+  },
+	  allowed_source_paths: stringArray(input.allowed_source_paths, "allowed_source_paths", { min: 1 }),
+	  excluded_source_paths: stringArray(input.excluded_source_paths ?? [], "excluded_source_paths"),
+	  clue_api_base_url: nonEmpty(input.clue_api_base_url, "clue_api_base_url"),
+	  ai_provider_base_url: optionalNonEmpty(input.ai_provider_base_url) ?? "https://api.openai.com/v1",
+	  ai_model: optionalNonEmpty(input.ai_model) ?? "gpt-5.4-mini",
+	});
+
+export const buildOperationSourceKey = (method, pathTemplate) =>
+  `route.${method.toUpperCase()}.${pathTemplate}`;
+
+export const validateSemanticSnapshotRequest = (input) => {
+  return parseWithSchema(semanticSnapshotRequestSchema, input, "semantic snapshot");
+};