@clue-ai/cli 0.0.8 → 0.0.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/src/contracts.mjs +132 -127
- package/src/lifecycle-init.mjs +184 -179
- package/src/public-schema.cjs +4 -0
- package/src/setup-check.mjs +3 -1
- package/src/setup-tool.mjs +388 -375
package/src/lifecycle-init.mjs
CHANGED
|
@@ -5,10 +5,10 @@ import { findLifecycleGuardViolations } from "./lifecycle-guard.mjs";
|
|
|
5
5
|
import { listAllowedSourceFiles } from "./path-policy.mjs";
|
|
6
6
|
|
|
7
7
|
const API_NAMES = new Set([
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
8
|
+
"ClueInit",
|
|
9
|
+
"ClueIdentify",
|
|
10
|
+
"ClueSetAccount",
|
|
11
|
+
"ClueLogout",
|
|
12
12
|
]);
|
|
13
13
|
|
|
14
14
|
const SOURCE_EXTENSIONS = [".py", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
|
|
@@ -17,208 +17,213 @@ const MAX_FILE_CHARS = 12_000;
|
|
|
17
17
|
const MAX_TOTAL_CHARS = 360_000;
|
|
18
18
|
|
|
19
19
|
const nonEmpty = (value, field) => {
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
20
|
+
if (typeof value !== "string" || value.trim() === "") {
|
|
21
|
+
throw new Error(`${field} is required`);
|
|
22
|
+
}
|
|
23
|
+
return value.trim();
|
|
24
24
|
};
|
|
25
25
|
|
|
26
26
|
const safeRelativePath = (repoRoot, filePath) => {
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
27
|
+
const root = resolve(repoRoot);
|
|
28
|
+
const absolutePath = resolve(root, filePath);
|
|
29
|
+
const relativePath = relative(root, absolutePath);
|
|
30
|
+
if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
|
|
31
|
+
throw new Error(`edit path escapes repo root: ${filePath}`);
|
|
32
|
+
}
|
|
33
|
+
return { absolutePath, relativePath };
|
|
34
34
|
};
|
|
35
35
|
|
|
36
36
|
const assertApiName = (apiName) => {
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
37
|
+
if (!API_NAMES.has(apiName)) {
|
|
38
|
+
throw new Error(`unsupported lifecycle API: ${apiName}`);
|
|
39
|
+
}
|
|
40
|
+
return apiName;
|
|
41
41
|
};
|
|
42
42
|
|
|
43
43
|
const assertNoForbiddenInstrumentation = (replacement) => {
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
44
|
+
if (replacement.includes("ClueTrack")) {
|
|
45
|
+
throw new Error("init tool must not add broad ClueTrack instrumentation");
|
|
46
|
+
}
|
|
47
|
+
if (/data-clue-(id|key)/i.test(replacement)) {
|
|
48
|
+
throw new Error("init tool must not add data-clue-id or data-clue-key");
|
|
49
|
+
}
|
|
50
50
|
};
|
|
51
51
|
|
|
52
52
|
const assertLifecycleCallsAreGuarded = (replacement) => {
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
53
|
+
const violations = findLifecycleGuardViolations(replacement);
|
|
54
|
+
if (violations.length > 0) {
|
|
55
|
+
throw new Error(
|
|
56
|
+
`Clue lifecycle calls must be failure-isolated with try/catch, try/except, or an explicit safe Clue helper: ${JSON.stringify(violations)}`,
|
|
57
|
+
);
|
|
58
|
+
}
|
|
59
59
|
};
|
|
60
60
|
|
|
61
61
|
const normalizeLifecycleInsertion = (input) => ({
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
62
|
+
api_name: assertApiName(nonEmpty(input.api_name, "api_name")),
|
|
63
|
+
file_path: nonEmpty(input.file_path, "file_path"),
|
|
64
|
+
confidence: Math.max(0, Math.min(1, Number(input.confidence ?? 0))),
|
|
65
|
+
reason: nonEmpty(input.reason, "reason"),
|
|
66
66
|
});
|
|
67
67
|
|
|
68
68
|
const normalizePlan = (input) => {
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
69
|
+
if (!input || typeof input !== "object") {
|
|
70
|
+
throw new Error("AI lifecycle plan must be an object");
|
|
71
|
+
}
|
|
72
|
+
if (!Array.isArray(input.edits)) {
|
|
73
|
+
throw new Error("AI lifecycle plan must include edits");
|
|
74
|
+
}
|
|
75
|
+
const edits = input.edits.map((edit) => ({
|
|
76
|
+
file_path: nonEmpty(edit.file_path, "edit.file_path"),
|
|
77
|
+
find: nonEmpty(edit.find, "edit.find"),
|
|
78
|
+
replace: nonEmpty(edit.replace, "edit.replace"),
|
|
79
|
+
}));
|
|
80
|
+
const lifecycleInsertions = Array.isArray(input.lifecycle_insertions)
|
|
81
|
+
? input.lifecycle_insertions.map(normalizeLifecycleInsertion)
|
|
82
|
+
: [];
|
|
83
|
+
return {
|
|
84
|
+
edits,
|
|
85
|
+
lifecycleInsertions,
|
|
86
|
+
warnings: Array.isArray(input.warnings)
|
|
87
|
+
? input.warnings
|
|
88
|
+
.filter((warning) => typeof warning === "string" && warning.trim())
|
|
89
|
+
.map((warning) => warning.trim())
|
|
90
|
+
: [],
|
|
91
|
+
};
|
|
92
92
|
};
|
|
93
93
|
|
|
94
94
|
export const applyLifecyclePlan = async ({ repoRoot, plan: rawPlan }) => {
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
95
|
+
const plan = normalizePlan(rawPlan);
|
|
96
|
+
for (const edit of plan.edits) {
|
|
97
|
+
const { absolutePath } = safeRelativePath(repoRoot, edit.file_path);
|
|
98
|
+
assertNoForbiddenInstrumentation(edit.replace);
|
|
99
|
+
const current = await readFile(absolutePath, "utf8");
|
|
100
|
+
const occurrences = current.split(edit.find).length - 1;
|
|
101
|
+
if (occurrences !== 1) {
|
|
102
|
+
throw new Error(
|
|
103
|
+
`edit.find must match exactly once in ${edit.file_path}; matched ${occurrences}`,
|
|
104
|
+
);
|
|
105
|
+
}
|
|
106
|
+
assertLifecycleCallsAreGuarded(edit.replace);
|
|
107
|
+
await writeFile(
|
|
108
|
+
absolutePath,
|
|
109
|
+
current.replace(edit.find, edit.replace),
|
|
110
|
+
"utf8",
|
|
111
|
+
);
|
|
112
|
+
}
|
|
113
|
+
return {
|
|
114
|
+
lifecycleInsertions: plan.lifecycleInsertions,
|
|
115
|
+
warnings: plan.warnings,
|
|
116
|
+
};
|
|
117
117
|
};
|
|
118
118
|
|
|
119
119
|
const readContextFiles = async ({ repoRoot, request }) => {
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
120
|
+
const files = await listAllowedSourceFiles({
|
|
121
|
+
repoRoot,
|
|
122
|
+
allowedSourcePaths: request.allowed_source_paths,
|
|
123
|
+
excludedSourcePaths: request.excluded_source_paths,
|
|
124
|
+
extensions: SOURCE_EXTENSIONS,
|
|
125
|
+
});
|
|
126
|
+
const context = [];
|
|
127
|
+
let totalChars = 0;
|
|
128
|
+
for (const absolutePath of files.slice(0, MAX_CONTEXT_FILES)) {
|
|
129
|
+
const text = await readFile(absolutePath, "utf8");
|
|
130
|
+
const snippet = text.slice(0, MAX_FILE_CHARS);
|
|
131
|
+
totalChars += snippet.length;
|
|
132
|
+
if (totalChars > MAX_TOTAL_CHARS) {
|
|
133
|
+
break;
|
|
134
|
+
}
|
|
135
|
+
context.push({
|
|
136
|
+
file_path: relative(resolve(repoRoot), absolutePath),
|
|
137
|
+
source: snippet,
|
|
138
|
+
truncated: text.length > snippet.length,
|
|
139
|
+
});
|
|
140
|
+
}
|
|
141
|
+
return context;
|
|
142
142
|
};
|
|
143
143
|
|
|
144
144
|
const buildLifecyclePrompt = ({ request, files }) =>
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
145
|
+
JSON.stringify({
|
|
146
|
+
task: "Add Clue SDK lifecycle API calls to this repository using exact text replacements.",
|
|
147
|
+
rules: [
|
|
148
|
+
"Return JSON only.",
|
|
149
|
+
"Use only exact replacements. Each find string must be copied exactly from source.",
|
|
150
|
+
"Add ClueInit, ClueIdentify, ClueSetAccount, and ClueLogout where repository code has clear lifecycle points.",
|
|
151
|
+
"Every Clue lifecycle call must be failure-isolated. If Clue fails, the host service must continue without throwing, rejecting, or blocking login/API behavior.",
|
|
152
|
+
"Use a small safe Clue helper, local try/catch/try/except wrapper, or direct .catch handler around Clue lifecycle calls.",
|
|
153
|
+
"Never await a Clue lifecycle call in a way that can block login, logout, account selection, request handling, page rendering, or API responses.",
|
|
154
|
+
"Find all clear login success paths and add ClueIdentify to every one of them. Do not stop after the first login flow.",
|
|
155
|
+
"Find all clear account, workspace, organization, or tenant resolution paths and add ClueSetAccount to every one of them.",
|
|
156
|
+
"Find all clear logout or session reset paths and add ClueLogout to every one of them.",
|
|
157
|
+
"Inspect backend lifecycle points as carefully as frontend lifecycle points. Backend login/session/account code is especially important.",
|
|
158
|
+
"For FastAPI backends, add the clue-fastapi-sdk dependency when missing, import clue_init_fastapi plus ClueIdentify/ClueSetAccount/ClueLogout where needed, and initialize the SDK at FastAPI app creation.",
|
|
159
|
+
"For Django backends, add the clue-django-sdk dependency when missing, import the Django SDK lifecycle helpers where needed, and initialize the SDK in the Django integration point.",
|
|
160
|
+
"For other backend frameworks, use the matching Clue backend SDK if one exists; if no backend SDK exists, report a blocker instead of silently frontend-only setup.",
|
|
161
|
+
"Do not add broad ClueTrack instrumentation.",
|
|
162
|
+
"Do not add data-clue-id, data-clue-key, or similar DOM tags.",
|
|
163
|
+
"Do not create route semantics files or layer files.",
|
|
164
|
+
"Do not copy project keys, API keys, service secrets, or environment-specific values into code.",
|
|
165
|
+
"Do not send raw email, raw person names, tokens, workspace names, organization names, or tenant names as lifecycle traits unless the repository already has an explicit Clue privacy policy allowing them.",
|
|
166
|
+
"Prefer stable ids and non-PII booleans/counts for ClueIdentify and ClueSetAccount traits.",
|
|
167
|
+
"Use environment variable names for Clue configuration values.",
|
|
168
|
+
"For Python/FastAPI code, read CLUE_PROJECT_KEY, CLUE_ENVIRONMENT, CLUE_API_KEY, and CLUE_INGEST_ENDPOINT from environment variables.",
|
|
169
|
+
"For browser code, read CLUE_PROJECT_KEY, CLUE_ENVIRONMENT, CLUE_SERVICE_KEY, and CLUE_INGEST_ENDPOINT from environment variables through the target framework's safe client config mechanism. Do not hard-code a Next.js-only prefix.",
|
|
170
|
+
"Never place CLUE_API_KEY in frontend code, frontend env files, browser bundles, or client-readable config.",
|
|
171
|
+
"When browser SDK ingest is configured, implement a backend-owned browser token endpoint that reads server-side CLUE_API_KEY and requests POST /api/v1/ingest/browser-tokens from Clue.",
|
|
172
|
+
"Configure frontend ClueInit with browserTokenProvider that calls the local backend token endpoint and returns the token string.",
|
|
173
|
+
"The browser token request must include project key, environment, service key, and the current browser origin; the backend must attach x-clue-api-key server-side when calling Clue.",
|
|
174
|
+
"Prefer minimal edits that engineers can review in one PR.",
|
|
175
|
+
"If a lifecycle point is unclear, skip that edit and include a warning.",
|
|
176
|
+
],
|
|
177
|
+
repository_context: {
|
|
178
|
+
target_tool: request.target_tool,
|
|
179
|
+
framework: request.framework,
|
|
180
|
+
project_key_env: "CLUE_PROJECT_KEY",
|
|
181
|
+
browser_project_key_env: "CLUE_PROJECT_KEY",
|
|
182
|
+
environment_env: "CLUE_ENVIRONMENT",
|
|
183
|
+
browser_environment_env: "CLUE_ENVIRONMENT",
|
|
184
|
+
clue_api_base_url_env: "CLUE_API_BASE_URL",
|
|
185
|
+
clue_ingest_endpoint_env: "CLUE_INGEST_ENDPOINT",
|
|
186
|
+
browser_ingest_endpoint_env: "CLUE_INGEST_ENDPOINT",
|
|
187
|
+
browser_token_endpoint_path: "/api/v1/ingest/browser-tokens",
|
|
188
|
+
service_key: request.service_key,
|
|
189
|
+
},
|
|
190
|
+
output_shape: {
|
|
191
|
+
edits: [
|
|
192
|
+
{
|
|
193
|
+
file_path: "app/main.py",
|
|
194
|
+
find: "exact original text",
|
|
195
|
+
replace: "exact replacement text",
|
|
196
|
+
},
|
|
197
|
+
],
|
|
198
|
+
lifecycle_insertions: [
|
|
199
|
+
{
|
|
200
|
+
api_name: "ClueInit",
|
|
201
|
+
file_path: "app/main.py",
|
|
202
|
+
confidence: 0.8,
|
|
203
|
+
reason: "SDK initialized where FastAPI app is created.",
|
|
204
|
+
},
|
|
205
|
+
],
|
|
206
|
+
warnings: ["short engineer review note"],
|
|
207
|
+
},
|
|
208
|
+
files,
|
|
209
|
+
});
|
|
205
210
|
|
|
206
211
|
export const planLifecycleInsertions = async ({ repoRoot, request, env }) => {
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
212
|
+
const apiKey = env.CLUE_AI_PROVIDER_API_KEY;
|
|
213
|
+
if (!apiKey) {
|
|
214
|
+
throw new Error(
|
|
215
|
+
"CLUE_AI_PROVIDER_API_KEY is required for lifecycle API insertion",
|
|
216
|
+
);
|
|
217
|
+
}
|
|
218
|
+
const files = await readContextFiles({ repoRoot, request });
|
|
219
|
+
return callJsonAiProvider({
|
|
220
|
+
config: resolveAiProviderConfig({ env, apiKey }),
|
|
221
|
+
system:
|
|
222
|
+
"You are a safe code-edit planner for Clue SDK initialization. Return schema-valid JSON only.",
|
|
223
|
+
user: buildLifecyclePrompt({ request, files }),
|
|
224
|
+
toolName: "return_lifecycle_plan",
|
|
225
|
+
toolDescription: "Return the Clue SDK lifecycle insertion plan.",
|
|
226
|
+
failureMessage: "AI provider failed during lifecycle planning",
|
|
227
|
+
emptyMessage: "AI provider returned empty lifecycle plan",
|
|
228
|
+
});
|
|
224
229
|
};
|
package/src/public-schema.cjs
CHANGED
|
@@ -76,6 +76,10 @@ const clueInitToolReportSchema = zod_1.z.object({
|
|
|
76
76
|
semantic_generation_timing: zod_1.z.literal("after_merge_ci"),
|
|
77
77
|
semantic_preview_generated: zod_1.z.literal(false),
|
|
78
78
|
client_repo_generated_files_committed: zod_1.z.literal(false),
|
|
79
|
+
frontend_api_key_exposed: zod_1.z.literal(false),
|
|
80
|
+
browser_token_endpoint_required: zod_1.z.literal(true),
|
|
81
|
+
browser_token_provider_required: zod_1.z.literal(true),
|
|
82
|
+
browser_token_endpoint_path: nonEmptyStringSchema,
|
|
79
83
|
clue_track_inserted: zod_1.z.literal(false),
|
|
80
84
|
clue_dom_tag_inserted: zod_1.z.literal(false),
|
|
81
85
|
allowed_source_paths: zod_1.z.array(nonEmptyStringSchema),
|
package/src/setup-check.mjs
CHANGED
|
@@ -440,10 +440,12 @@ export const runSetupCheck = async ({
|
|
|
440
440
|
checks,
|
|
441
441
|
"sdk_lifecycle",
|
|
442
442
|
sdkLifecycle.passed,
|
|
443
|
-
"SDK lifecycle
|
|
443
|
+
"static SDK lifecycle references are present and guarded; dependency install, import, app startup, and event delivery are not verified by this check",
|
|
444
444
|
{
|
|
445
445
|
found_apis: sdkLifecycle.foundApis,
|
|
446
446
|
missing_apis: sdkLifecycle.missingApis,
|
|
447
|
+
verification_scope:
|
|
448
|
+
"static_source_only_not_dependency_install_or_runtime_event_delivery",
|
|
447
449
|
backend_lifecycle: sdkLifecycle.backend_lifecycle,
|
|
448
450
|
has_noop_wrapper: sdkLifecycle.has_noop_wrapper,
|
|
449
451
|
component_lifecycle_init_files:
|