@agentspec/cli 0.1.0 → 0.2.1
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/dist/cli.js +271 -20
- package/dist/cli.js.map +1 -1
- package/package.json +17 -7
package/dist/cli.js
CHANGED
|
@@ -2,6 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
// src/cli.ts
|
|
4
4
|
import { Command } from "commander";
|
|
5
|
+
import { readFileSync as readFileSync6 } from "fs";
|
|
6
|
+
import { fileURLToPath } from "url";
|
|
7
|
+
import { dirname as dirname3, join as join5 } from "path";
|
|
5
8
|
|
|
6
9
|
// src/commands/validate.ts
|
|
7
10
|
import chalk2 from "chalk";
|
|
@@ -444,7 +447,7 @@ function registerInitCommand(program2) {
|
|
|
444
447
|
}
|
|
445
448
|
let name = "my-agent";
|
|
446
449
|
let description = "An AI agent";
|
|
447
|
-
let
|
|
450
|
+
let version2 = "0.1.0";
|
|
448
451
|
let provider = "openai";
|
|
449
452
|
let modelId = "gpt-4o-mini";
|
|
450
453
|
let includeMemory = false;
|
|
@@ -505,7 +508,7 @@ function registerInitCommand(program2) {
|
|
|
505
508
|
);
|
|
506
509
|
name = String(answers.name || "my-agent");
|
|
507
510
|
description = String(answers.description || "An AI agent");
|
|
508
|
-
|
|
511
|
+
version2 = String(answers.version || "0.1.0");
|
|
509
512
|
provider = String(answers.provider || "openai");
|
|
510
513
|
modelId = String(answers.modelId || "gpt-4o-mini");
|
|
511
514
|
includeMemory = Boolean(answers.includeMemory);
|
|
@@ -516,7 +519,7 @@ function registerInitCommand(program2) {
|
|
|
516
519
|
const yaml3 = generateManifest({
|
|
517
520
|
name,
|
|
518
521
|
description,
|
|
519
|
-
version,
|
|
522
|
+
version: version2,
|
|
520
523
|
provider,
|
|
521
524
|
modelId,
|
|
522
525
|
apiKeyEnv,
|
|
@@ -644,7 +647,33 @@ spec:
|
|
|
644
647
|
import { existsSync as existsSync2, mkdirSync, readFileSync, writeFileSync as writeFileSync3 } from "fs";
|
|
645
648
|
import { basename, dirname, join as join2, resolve as resolve2, sep } from "path";
|
|
646
649
|
import chalk6 from "chalk";
|
|
647
|
-
|
|
650
|
+
|
|
651
|
+
// src/utils/spinner.ts
|
|
652
|
+
import { spinner as clackSpinner } from "@clack/prompts";
|
|
653
|
+
function createFallbackSpinner() {
|
|
654
|
+
let _current = "";
|
|
655
|
+
return {
|
|
656
|
+
start(msg) {
|
|
657
|
+
if (msg) _current = msg;
|
|
658
|
+
console.log(_current);
|
|
659
|
+
},
|
|
660
|
+
stop(msg) {
|
|
661
|
+
if (msg) _current = msg;
|
|
662
|
+
console.log(_current);
|
|
663
|
+
},
|
|
664
|
+
message(msg) {
|
|
665
|
+
if (msg) _current = msg;
|
|
666
|
+
}
|
|
667
|
+
};
|
|
668
|
+
}
|
|
669
|
+
function spinner() {
|
|
670
|
+
if (process.stdout.isTTY) {
|
|
671
|
+
return clackSpinner();
|
|
672
|
+
}
|
|
673
|
+
return createFallbackSpinner();
|
|
674
|
+
}
|
|
675
|
+
|
|
676
|
+
// src/commands/generate.ts
|
|
648
677
|
import { loadManifest as loadManifest4 } from "@agentspec/sdk";
|
|
649
678
|
import { generateWithClaude, listFrameworks } from "@agentspec/adapter-claude";
|
|
650
679
|
|
|
@@ -1142,10 +1171,178 @@ import {
|
|
|
1142
1171
|
writeFileSync as writeFileSync5
|
|
1143
1172
|
} from "fs";
|
|
1144
1173
|
import { extname, join as join3, resolve as resolve4 } from "path";
|
|
1145
|
-
import
|
|
1146
|
-
import { generateWithClaude as generateWithClaude2 } from "@agentspec/adapter-claude";
|
|
1174
|
+
import * as jsYaml from "js-yaml";
|
|
1175
|
+
import { generateWithClaude as generateWithClaude2, repairYaml } from "@agentspec/adapter-claude";
|
|
1176
|
+
import { ManifestSchema } from "@agentspec/sdk";
|
|
1177
|
+
|
|
1178
|
+
// src/commands/scan-builder.ts
|
|
1179
|
+
function buildMetadata(d) {
|
|
1180
|
+
return {
|
|
1181
|
+
name: slugify(d.name),
|
|
1182
|
+
version: d.version ?? "0.1.0",
|
|
1183
|
+
description: d.description,
|
|
1184
|
+
...d.tags?.length ? { tags: d.tags } : {}
|
|
1185
|
+
};
|
|
1186
|
+
}
|
|
1187
|
+
function buildModel(d) {
|
|
1188
|
+
const model = {
|
|
1189
|
+
provider: d.modelProvider,
|
|
1190
|
+
id: d.modelId,
|
|
1191
|
+
apiKey: `$env:${d.modelApiKeyEnv}`
|
|
1192
|
+
};
|
|
1193
|
+
if (d.modelTemperature !== void 0 || d.modelMaxTokens !== void 0) {
|
|
1194
|
+
model.parameters = {
|
|
1195
|
+
...d.modelTemperature !== void 0 ? { temperature: d.modelTemperature } : {},
|
|
1196
|
+
...d.modelMaxTokens !== void 0 ? { maxTokens: d.modelMaxTokens } : {}
|
|
1197
|
+
};
|
|
1198
|
+
}
|
|
1199
|
+
if (d.fallbackProvider && d.fallbackModelId) {
|
|
1200
|
+
model.fallback = {
|
|
1201
|
+
provider: d.fallbackProvider,
|
|
1202
|
+
id: d.fallbackModelId,
|
|
1203
|
+
apiKey: `$env:${d.fallbackApiKeyEnv ?? d.modelApiKeyEnv}`,
|
|
1204
|
+
triggerOn: ["rate_limit", "timeout", "error_5xx"]
|
|
1205
|
+
};
|
|
1206
|
+
}
|
|
1207
|
+
return model;
|
|
1208
|
+
}
|
|
1209
|
+
function buildPrompts(d) {
|
|
1210
|
+
return {
|
|
1211
|
+
system: d.promptFile ? `$file:${d.promptFile}` : "$file:system.md",
|
|
1212
|
+
hotReload: false
|
|
1213
|
+
};
|
|
1214
|
+
}
|
|
1215
|
+
function buildTools(d) {
|
|
1216
|
+
if (!d.tools?.length) return void 0;
|
|
1217
|
+
return d.tools.map((t) => ({
|
|
1218
|
+
name: slugify(t.name),
|
|
1219
|
+
type: "function",
|
|
1220
|
+
description: t.description,
|
|
1221
|
+
...t.module ? { module: `$file:${t.module}` } : {},
|
|
1222
|
+
...t.function ? { function: t.function } : {},
|
|
1223
|
+
...t.readOnly !== void 0 || t.destructive !== void 0 || t.idempotent !== void 0 ? {
|
|
1224
|
+
annotations: {
|
|
1225
|
+
...t.readOnly !== void 0 ? { readOnlyHint: t.readOnly } : {},
|
|
1226
|
+
...t.destructive !== void 0 ? { destructiveHint: t.destructive } : {},
|
|
1227
|
+
...t.idempotent !== void 0 ? { idempotentHint: t.idempotent } : {}
|
|
1228
|
+
}
|
|
1229
|
+
} : {}
|
|
1230
|
+
}));
|
|
1231
|
+
}
|
|
1232
|
+
function buildMemory(d) {
|
|
1233
|
+
const memory = {};
|
|
1234
|
+
let hasAny = false;
|
|
1235
|
+
if (d.shortTermBackend) {
|
|
1236
|
+
hasAny = true;
|
|
1237
|
+
const shortTerm = {
|
|
1238
|
+
backend: d.shortTermBackend,
|
|
1239
|
+
...d.shortTermMaxTurns !== void 0 ? { maxTurns: d.shortTermMaxTurns } : {},
|
|
1240
|
+
...d.shortTermTtlSeconds !== void 0 ? { ttlSeconds: d.shortTermTtlSeconds } : {}
|
|
1241
|
+
};
|
|
1242
|
+
if (d.shortTermBackend !== "in-memory" && d.shortTermConnectionEnv) {
|
|
1243
|
+
shortTerm.connection = `$env:${d.shortTermConnectionEnv}`;
|
|
1244
|
+
}
|
|
1245
|
+
memory.shortTerm = shortTerm;
|
|
1246
|
+
}
|
|
1247
|
+
if (d.longTermBackend && d.longTermConnectionStringEnv) {
|
|
1248
|
+
hasAny = true;
|
|
1249
|
+
memory.longTerm = {
|
|
1250
|
+
backend: d.longTermBackend,
|
|
1251
|
+
connectionString: `$env:${d.longTermConnectionStringEnv}`
|
|
1252
|
+
};
|
|
1253
|
+
}
|
|
1254
|
+
return hasAny ? memory : void 0;
|
|
1255
|
+
}
|
|
1256
|
+
function buildGuardrails(d) {
|
|
1257
|
+
const input = [];
|
|
1258
|
+
const output = [];
|
|
1259
|
+
if (d.hasPromptInjection) {
|
|
1260
|
+
input.push({ type: "prompt-injection", action: "reject" });
|
|
1261
|
+
}
|
|
1262
|
+
if (d.hasTopicFilter && d.blockedTopics?.length) {
|
|
1263
|
+
input.push({ type: "topic-filter", blockedTopics: d.blockedTopics, action: "reject" });
|
|
1264
|
+
}
|
|
1265
|
+
if (d.hasPiiDetector) {
|
|
1266
|
+
input.push({ type: "pii-detector", action: "scrub" });
|
|
1267
|
+
}
|
|
1268
|
+
if (d.hasToxicityFilter) {
|
|
1269
|
+
output.push({
|
|
1270
|
+
type: "toxicity-filter",
|
|
1271
|
+
threshold: d.toxicityThreshold ?? 0.8,
|
|
1272
|
+
action: "reject"
|
|
1273
|
+
});
|
|
1274
|
+
}
|
|
1275
|
+
if (!input.length && !output.length) return void 0;
|
|
1276
|
+
return {
|
|
1277
|
+
...input.length ? { input } : {},
|
|
1278
|
+
...output.length ? { output } : {}
|
|
1279
|
+
};
|
|
1280
|
+
}
|
|
1281
|
+
function buildApi(d) {
|
|
1282
|
+
if (!d.hasRestApi) return void 0;
|
|
1283
|
+
return {
|
|
1284
|
+
type: "rest",
|
|
1285
|
+
...d.apiPort !== void 0 ? { port: d.apiPort } : {},
|
|
1286
|
+
...d.apiAuthType ? { auth: { type: d.apiAuthType } } : {},
|
|
1287
|
+
streaming: d.apiStreaming ?? false
|
|
1288
|
+
};
|
|
1289
|
+
}
|
|
1290
|
+
function buildObservability(d) {
|
|
1291
|
+
const hasTracing = !!d.tracingBackend;
|
|
1292
|
+
const hasMetrics = !!d.metricsBackend;
|
|
1293
|
+
const hasLogging = d.loggingStructured !== void 0;
|
|
1294
|
+
if (!hasTracing && !hasMetrics && !hasLogging) return void 0;
|
|
1295
|
+
return {
|
|
1296
|
+
...hasTracing ? { tracing: { backend: d.tracingBackend, sampleRate: 1 } } : {},
|
|
1297
|
+
...hasMetrics ? { metrics: { backend: d.metricsBackend, serviceName: slugify(d.name) } } : {},
|
|
1298
|
+
...hasLogging ? { logging: { level: "info", structured: d.loggingStructured ?? true } } : {}
|
|
1299
|
+
};
|
|
1300
|
+
}
|
|
1301
|
+
function buildCompliance() {
|
|
1302
|
+
return {
|
|
1303
|
+
packs: ["owasp-llm-top10", "model-resilience", "memory-hygiene"]
|
|
1304
|
+
};
|
|
1305
|
+
}
|
|
1306
|
+
function buildRequires(d) {
|
|
1307
|
+
const hasEnvVars = d.envVars.length > 0;
|
|
1308
|
+
const hasServices = !!d.services?.length;
|
|
1309
|
+
if (!hasEnvVars && !hasServices) return void 0;
|
|
1310
|
+
return {
|
|
1311
|
+
...hasEnvVars ? { envVars: d.envVars } : {},
|
|
1312
|
+
...hasServices ? {
|
|
1313
|
+
services: d.services.map((s) => ({
|
|
1314
|
+
type: s.type,
|
|
1315
|
+
connection: `$env:${s.connectionEnv}`
|
|
1316
|
+
}))
|
|
1317
|
+
} : {}
|
|
1318
|
+
};
|
|
1319
|
+
}
|
|
1320
|
+
function slugify(s) {
|
|
1321
|
+
return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
|
|
1322
|
+
}
|
|
1323
|
+
function buildManifestFromDetection(d) {
|
|
1324
|
+
return {
|
|
1325
|
+
apiVersion: "agentspec.io/v1",
|
|
1326
|
+
kind: "AgentSpec",
|
|
1327
|
+
metadata: buildMetadata(d),
|
|
1328
|
+
spec: {
|
|
1329
|
+
model: buildModel(d),
|
|
1330
|
+
prompts: buildPrompts(d),
|
|
1331
|
+
tools: buildTools(d),
|
|
1332
|
+
memory: buildMemory(d),
|
|
1333
|
+
guardrails: buildGuardrails(d),
|
|
1334
|
+
api: buildApi(d),
|
|
1335
|
+
observability: buildObservability(d),
|
|
1336
|
+
compliance: buildCompliance(),
|
|
1337
|
+
requires: buildRequires(d)
|
|
1338
|
+
}
|
|
1339
|
+
};
|
|
1340
|
+
}
|
|
1341
|
+
|
|
1342
|
+
// src/commands/scan.ts
|
|
1147
1343
|
var MAX_FILES = 50;
|
|
1148
1344
|
var MAX_BYTES = 200 * 1024;
|
|
1345
|
+
var MAX_REPAIR_ITERATIONS = 2;
|
|
1149
1346
|
var SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([".py", ".ts", ".js", ".mjs", ".cjs"]);
|
|
1150
1347
|
var SKIP_DIRS = /* @__PURE__ */ new Set([
|
|
1151
1348
|
"node_modules",
|
|
@@ -1252,17 +1449,39 @@ function collectAndValidateSourceFiles(srcDir) {
|
|
|
1252
1449
|
}
|
|
1253
1450
|
return files;
|
|
1254
1451
|
}
|
|
1255
|
-
function
|
|
1452
|
+
function parseDetection(rawResult) {
|
|
1256
1453
|
if (!rawResult || typeof rawResult !== "object" || !("files" in rawResult) || typeof rawResult.files !== "object" || rawResult.files === null) {
|
|
1257
|
-
|
|
1258
|
-
process.exit(1);
|
|
1454
|
+
throw new Error('Claude returned an unexpected response format (missing "files" object).');
|
|
1259
1455
|
}
|
|
1260
|
-
const
|
|
1261
|
-
if (!
|
|
1262
|
-
|
|
1263
|
-
|
|
1456
|
+
const detectionJson = rawResult.files["detection.json"];
|
|
1457
|
+
if (!detectionJson) {
|
|
1458
|
+
throw new Error("Claude did not return detection.json in the output.");
|
|
1459
|
+
}
|
|
1460
|
+
let detection;
|
|
1461
|
+
try {
|
|
1462
|
+
detection = JSON.parse(detectionJson);
|
|
1463
|
+
} catch (e) {
|
|
1464
|
+
throw new Error(`Failed to parse detection JSON: ${e.message}`);
|
|
1465
|
+
}
|
|
1466
|
+
const requiredFields = ["name", "description", "modelProvider", "modelId", "modelApiKeyEnv"];
|
|
1467
|
+
const missing = requiredFields.filter((f) => !detection[f]);
|
|
1468
|
+
if (!Array.isArray(detection.envVars)) missing.push("envVars");
|
|
1469
|
+
if (missing.length) {
|
|
1470
|
+
throw new Error(`Detection JSON is missing required fields: ${missing.join(", ")}`);
|
|
1471
|
+
}
|
|
1472
|
+
return detection;
|
|
1473
|
+
}
|
|
1474
|
+
function validateManifestYaml(yamlStr) {
|
|
1475
|
+
let parsed;
|
|
1476
|
+
try {
|
|
1477
|
+
parsed = jsYaml.load(yamlStr);
|
|
1478
|
+
} catch (e) {
|
|
1479
|
+
return { valid: false, errors: `YAML parse error: ${e.message}`, errorCount: 1 };
|
|
1264
1480
|
}
|
|
1265
|
-
|
|
1481
|
+
const result = ManifestSchema.safeParse(parsed);
|
|
1482
|
+
if (result.success) return { valid: true };
|
|
1483
|
+
const errors = result.error.errors.map((e) => ` - ${e.path.join(".") || "(root)"}: ${e.message}`).join("\n");
|
|
1484
|
+
return { valid: false, errors, errorCount: result.error.errors.length };
|
|
1266
1485
|
}
|
|
1267
1486
|
function registerScanCommand(program2) {
|
|
1268
1487
|
program2.command("scan").description("Scan source code and generate an agent.yaml manifest (Claude-powered)").requiredOption("-d, --dir <src>", "Source directory to scan").option("--out <path>", "Explicit output path").option("--update", "Overwrite existing agent.yaml in place").option("--dry-run", "Print generated YAML to stdout without writing").action(async (opts) => {
|
|
@@ -1274,14 +1493,14 @@ function registerScanCommand(program2) {
|
|
|
1274
1493
|
}
|
|
1275
1494
|
const srcDir = resolve4(opts.dir);
|
|
1276
1495
|
const sourceFiles = collectAndValidateSourceFiles(srcDir);
|
|
1277
|
-
const s =
|
|
1278
|
-
s.start("Analysing source code
|
|
1496
|
+
const s = spinner();
|
|
1497
|
+
s.start("Analysing source code\u2026");
|
|
1279
1498
|
let rawResult;
|
|
1280
1499
|
try {
|
|
1281
1500
|
rawResult = await generateWithClaude2(
|
|
1282
1501
|
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
1283
1502
|
{},
|
|
1284
|
-
// empty manifest — the scan skill
|
|
1503
|
+
// empty manifest — the scan skill detects from source
|
|
1285
1504
|
{
|
|
1286
1505
|
framework: "scan",
|
|
1287
1506
|
contextFiles: sourceFiles.map((f) => f.path),
|
|
@@ -1293,8 +1512,38 @@ function registerScanCommand(program2) {
|
|
|
1293
1512
|
console.error(`Scan failed: ${err.message}`);
|
|
1294
1513
|
process.exit(1);
|
|
1295
1514
|
}
|
|
1296
|
-
|
|
1297
|
-
|
|
1515
|
+
let agentYaml;
|
|
1516
|
+
try {
|
|
1517
|
+
s.message("Building manifest\u2026");
|
|
1518
|
+
const detection = parseDetection(rawResult);
|
|
1519
|
+
const manifest = buildManifestFromDetection(detection);
|
|
1520
|
+
agentYaml = jsYaml.dump(manifest, { lineWidth: 120 });
|
|
1521
|
+
} catch (err) {
|
|
1522
|
+
s.stop("Failed");
|
|
1523
|
+
console.error(`Build failed: ${err.message}`);
|
|
1524
|
+
process.exit(1);
|
|
1525
|
+
}
|
|
1526
|
+
let validation = validateManifestYaml(agentYaml);
|
|
1527
|
+
for (let attempt = 1; !validation.valid && attempt <= MAX_REPAIR_ITERATIONS; attempt++) {
|
|
1528
|
+
s.message(
|
|
1529
|
+
`Fixing ${validation.errorCount} schema error(s) \u2014 attempt ${attempt}/${MAX_REPAIR_ITERATIONS}\u2026`
|
|
1530
|
+
);
|
|
1531
|
+
try {
|
|
1532
|
+
agentYaml = await repairYaml(agentYaml, validation.errors);
|
|
1533
|
+
validation = validateManifestYaml(agentYaml);
|
|
1534
|
+
} catch (err) {
|
|
1535
|
+
s.stop("Failed");
|
|
1536
|
+
console.error(`Repair failed: ${err.message}`);
|
|
1537
|
+
process.exit(1);
|
|
1538
|
+
}
|
|
1539
|
+
}
|
|
1540
|
+
if (validation.valid) {
|
|
1541
|
+
s.stop("Analysis complete \u2713");
|
|
1542
|
+
} else {
|
|
1543
|
+
s.stop(`Analysis complete (${validation.errorCount} schema error(s) remain \u2014 review the file)`);
|
|
1544
|
+
agentYaml = `# agentspec validate errors \u2014 fix before committing:
|
|
1545
|
+
` + validation.errors.split("\n").map((l) => `# ${l}`).join("\n") + "\n\n" + agentYaml;
|
|
1546
|
+
}
|
|
1298
1547
|
if (opts.dryRun) {
|
|
1299
1548
|
console.log(agentYaml);
|
|
1300
1549
|
return;
|
|
@@ -2074,8 +2323,10 @@ function resolvePython() {
|
|
|
2074
2323
|
}
|
|
2075
2324
|
|
|
2076
2325
|
// src/cli.ts
|
|
2326
|
+
var _dir = dirname3(fileURLToPath(import.meta.url));
|
|
2327
|
+
var { version } = JSON.parse(readFileSync6(join5(_dir, "../package.json"), "utf8"));
|
|
2077
2328
|
var program = new Command();
|
|
2078
|
-
program.name("agentspec").description("Universal Agent Manifest System \u2014 validate, health-check, audit, and generate agents").version(
|
|
2329
|
+
program.name("agentspec").description("Universal Agent Manifest System \u2014 validate, health-check, audit, and generate agents").version(version);
|
|
2079
2330
|
registerValidateCommand(program);
|
|
2080
2331
|
registerHealthCommand(program);
|
|
2081
2332
|
registerAuditCommand(program);
|