@naturali/cli 0.132.0 → 0.133.1

package/README.md

@@ -54,9 +54,42 @@ the spec, so you never have to know.
 | Number / boolean | `--temperature 0.7`, `--force` (a bare flag is `true`) |
 | Object | `--tool-choice '{"type":"tool","name":"get_weather"}'` |
 | Array | repeat the flag (`--capabilities a --capabilities b`) or pass a JSON array (`--tool-bindings '[{"tool_id":"tool_a"}]'`) |
+| From a file | `--content @playbook.md` (`@@` sends a literal leading `@`) |
 
 An array-typed field is always sent as a list, even with one value.
 
+### File values
+
+`@path` reads the value from disk. A `.yaml`, `.yml` or `.json` file is parsed,
+and a `{ "file": "..." }` inside it is replaced by that file's contents,
+resolved relative to the document holding the reference:
+
+```yaml
+# naturali/squad.formation.yaml
+resources:
+  Playbook:
+    type: document
+    properties:
+      path: /squad/playbook.md
+      content:
+        file: ../intelligence/playbook.md
+```
+
+```bash
+naturali validate-formation --project-id proj_V1StGXR8Z5jdHi6B \
+  --template @naturali/squad.formation.yaml
+```
+
+That is what lets a formation template declare documents whose text is versioned
+beside it, instead of carrying a pasted copy of each. Any other extension is read
+as text and never parsed, so a markdown file opening with `{` stays a string.
+
+Only a lone `{ "file": ... }` is a reference — an object with other keys beside
+it is left alone, so a property genuinely named `file` is not hijacked.
+
+A template can read any file you can. Read one you did not write before
+deploying it.
+
 Every path parameter a command needs must be passed explicitly; a command that
 leaves one out fails and names it rather than guessing.
 

package/dist/index.mjs

@@ -1,6 +1,9 @@
 import * as nodePath from "node:path";
+import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { parse } from "yaml";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
@@ -14,7 +17,7 @@ var __exportAll = (all, no_symbols) => {
 };
 //#endregion
 //#region package.json
-var version = "0.132.0";
+var version = "0.133.1";
 //#endregion
 //#region ../sdk/src/generated/core/bodySerializer.gen.ts
 const serializeFormDataPair = (data, key, value) => {
@@ -5216,13 +5219,13 @@ const parseStringFlagValue = (value) => {
 *
 * An array *of objects* — `tool_bindings` — has only the literal form:
 * `--tool-bindings '[{"tool_id":"tool_a"}]'`.
+*
+* Values arrive already coerced, because an item may have come from a `@file`
+* reference and must keep the type its file declared.
 */
-const buildArrayFlagValue = (rawValues) => {
-	const parsed = rawValues.map((value) => {
-		return parseFlagValue(value);
-	});
-	if (parsed.length === 1 && Array.isArray(parsed[0])) return parsed[0];
-	return parsed;
+const buildArrayFlagValue = (values) => {
+	if (values.length === 1 && Array.isArray(values[0])) return values[0];
+	return values;
 };
 //#endregion
 //#region src/help.ts
@@ -5279,16 +5282,174 @@ const renderCommandHelp = (args) => {
 	return lines.join("\n");
 };
 //#endregion
+//#region src/fileValues.ts
+/**
+* File references in flag values.
+*
+* A flag value written `@path` is read from disk instead of the command line.
+* That covers the two shapes a shell makes awkward: a long text field whose
+* content is already a file (`--content @playbook.md`), and a structured
+* document that itself names other files.
+*
+* A structured reference — `.yaml`, `.yml` or `.json` — is parsed, and any
+* `{ "file": "..." }` inside it is replaced by that file's contents, resolved
+* relative to the document holding the reference. That is what lets one
+* formation template declare documents whose text is versioned beside it,
+* rather than carrying a pasted copy of each.
+*
+* A template can read any file the caller can, as `curl -d @file` can — which
+* is the reason to read a template you did not write before deploying it.
+*/
+/** How deep `{ "file": ... }` references may nest before we call it a cycle. */
+const MAX_DEPTH = 10;
+const STRUCTURED = /\.(ya?ml|json)$/i;
+/** `@@` escapes a leading `@`, for a value that really starts with one. */
+const isFileReference = (raw) => {
+	return raw.startsWith("@") && !raw.startsWith("@@");
+};
+/** Strips the escape from a literal value that begins with `@@`. */
+const unescapeLeadingAt = (raw) => {
+	return raw.startsWith("@@") ? raw.slice(1) : raw;
+};
+var FileValueError = class extends Error {};
+const readText = (args) => {
+	const { path } = args;
+	try {
+		return readFileSync(path, "utf8");
+	} catch (error) {
+		throw new FileValueError(`cannot read ${path}: ${error instanceof Error && "code" in error && error.code === "ENOENT" ? "no such file" : error instanceof Error ? error.message : String(error)}`);
+	}
+};
+const parseStructured = (args) => {
+	const { path, text } = args;
+	try {
+		return parse(text);
+	} catch (error) {
+		throw new FileValueError(`cannot parse ${path}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+};
+/**
+* A lone `{ file: "..." }` is a reference; an object with other keys beside it
+* is not, so a property genuinely named `file` keeps its value.
+*/
+const referenceTarget = (node) => {
+	if (typeof node !== "object" || node === null || Array.isArray(node)) return;
+	const keys = Object.keys(node);
+	if (keys.length !== 1 || keys[0] !== "file") return;
+	const target = node.file;
+	return typeof target === "string" ? target : void 0;
+};
+/**
+* Walks a parsed document, replacing each reference with what it names. One
+* function rather than two: reading a structured file resumes the same walk on
+* its contents, so splitting it would only make the recursion mutual.
+*/
+const expand = (args) => {
+	const { node, baseDir, depth } = args;
+	const target = referenceTarget(node);
+	if (target !== void 0) {
+		if (depth >= MAX_DEPTH) throw new FileValueError(`file references nested more than ${MAX_DEPTH} deep — a reference cycle?`);
+		const path = resolve(baseDir, target);
+		const text = readText({ path });
+		if (!STRUCTURED.test(path)) return text;
+		return expand({
+			node: parseStructured({
+				path,
+				text
+			}),
+			baseDir: dirname(path),
+			depth: depth + 1
+		});
+	}
+	if (Array.isArray(node)) return node.map((item) => {
+		return expand({
+			node: item,
+			baseDir,
+			depth
+		});
+	});
+	if (typeof node === "object" && node !== null) return Object.fromEntries(Object.entries(node).map(([key, value]) => {
+		return [key, expand({
+			node: value,
+			baseDir,
+			depth
+		})];
+	}));
+	return node;
+};
+/**
+* Resolves one raw flag value.
+*
+* `fromFile` tells the caller the value already has the type its file
+* declared, so it must skip the string coercions: those exist to guess a JSON
+* value out of a shell word, and a file has nothing to guess about.
+*/
+const resolveFlagValue = (args) => {
+	const { raw } = args;
+	if (!isFileReference(raw)) return {
+		ok: true,
+		value: unescapeLeadingAt(raw),
+		fromFile: false
+	};
+	const reference = raw.slice(1);
+	if (reference === "") return {
+		ok: false,
+		message: "\"@\" needs a path after it."
+	};
+	try {
+		return {
+			ok: true,
+			value: expand({
+				node: { file: reference },
+				baseDir: process.cwd(),
+				depth: 0
+			}),
+			fromFile: true
+		};
+	} catch (error) {
+		if (error instanceof FileValueError) return {
+			ok: false,
+			message: error.message
+		};
+		throw error;
+	}
+};
+//#endregion
 //#region src/routeCall.ts
 const placeFlags = (args) => {
 	const { route, parsedFlags, call } = args;
+	const fileErrors = [];
+	/**
+	* A value read from a file is used as the file declared it. Only a value
+	* still in its shell spelling goes through `coerce`, which guesses a JSON
+	* type out of a word.
+	*/
+	const readValue = (readArgs) => {
+		const { flagKey, raw, coerce } = readArgs;
+		const resolved = resolveFlagValue({ raw });
+		if (!resolved.ok) {
+			fileErrors.push(`--${flagKey}: ${resolved.message}`);
+			return;
+		}
+		return resolved.fromFile ? resolved.value : coerce(resolved.value);
+	};
 	const typeByCanonical = new Map(route.flags.map((flag) => {
 		return [toCanonical(flag.name), flag.type];
 	}));
 	for (const [flagKey, rawValue] of Object.entries(parsedFlags.single)) {
 		const canonical = toCanonical(flagKey);
 		const declaredType = typeByCanonical.get(canonical);
-		const value = declaredType === "array" ? buildArrayFlagValue(parsedFlags.repeated[flagKey] ?? [rawValue]) : declaredType === "string" ? parseStringFlagValue(rawValue) : parseFlagValue(rawValue);
+		const value = declaredType === "array" ? buildArrayFlagValue((parsedFlags.repeated[flagKey] ?? [rawValue]).map((item) => {
+			return readValue({
+				flagKey,
+				raw: item,
+				coerce: parseFlagValue
+			});
+		})) : readValue({
+			flagKey,
+			raw: rawValue,
+			coerce: declaredType === "string" ? parseStringFlagValue : parseFlagValue
+		});
 		const pathParam = route.pathParams.find((param) => {
 			return toCanonical(param) === canonical;
 		});
@@ -5309,6 +5470,7 @@ const placeFlags = (args) => {
 		}
 		call.body[kebabToSnake(flagKey)] = value;
 	}
+	return fileErrors;
 };
 const PROJECT_ID_PARAM = "project_id";
 /**
@@ -5336,11 +5498,16 @@ const buildRouteCall = (args) => {
 		query: {},
 		body: {}
 	};
-	placeFlags({
+	const fileErrors = placeFlags({
 		route,
 		parsedFlags,
 		call
 	});
+	if (fileErrors.length > 0) return {
+		ok: false,
+		kind: "file_errors",
+		fileErrors
+	};
 	applyProjectIdEnvDefault({
 		route,
 		call
@@ -5350,6 +5517,7 @@ const buildRouteCall = (args) => {
 	});
 	if (missingPathParams.length > 0) return {
 		ok: false,
+		kind: "missing_path_params",
 		missingPathParams
 	};
 	return {
@@ -5494,6 +5662,10 @@ const dispatchCommand = async (args) => {
 		route,
 		parsedFlags
 	});
+	if (!built.ok && built.kind === "file_errors") {
+		console.error(built.fileErrors.join("\n"));
+		process.exit(1);
+	}
 	if (!built.ok) {
 		const flagsHint = built.missingPathParams.map((param) => {
 			return `--${param.replace(/_/g, "-")} <value>`;
@@ -5828,7 +6000,7 @@ const routes = {
 			},
 			{
 				"name": "tags",
-				"description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter and knowledge search.",
+				"description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter and knowledge search.\n\nKeys beginning `system.` are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -9320,6 +9492,13 @@ const routes = {
 				"required": false,
 				"type": "string",
 				"in": "body"
+			},
+			{
+				"name": "retrieval",
+				"description": "Whether this conversation's turns are embedded for vector retrieval. Turns are stored and chunked either way, so `none` leaves them readable and reachable by full-text search without paying for an embedding. `null` (the default) inherits the project's `default_conversation_retrieval`.",
+				"required": false,
+				"type": "string",
+				"in": "body"
 			}
 		]
 	},
@@ -9385,6 +9564,13 @@ const routes = {
 				"required": false,
 				"type": "string",
 				"in": "body"
+			},
+			{
+				"name": "retrieval",
+				"description": "Whether this conversation's turns are embedded for vector retrieval. Turns are stored and chunked either way, so `none` leaves them readable and reachable by full-text search without paying for an embedding. `null` (the default) inherits the project's `default_conversation_retrieval`. Switching it on embeds the turns already in the conversation, so the whole conversation becomes retrievable rather than only what is said next.",
+				"required": false,
+				"type": "string",
+				"in": "body"
 			}
 		]
 	},
@@ -9767,7 +9953,7 @@ const routes = {
 			},
 			{
 				"name": "path",
-				"description": "Logical path within the project (e.g. /reports/q1.txt). Defaults to /filename if omitted.",
+				"description": "Logical path within the project (e.g. /reports/q1.txt). Defaults to `/<filename>`, or to `/<document_id>.txt` when neither is given — a document with no path is reachable only by its id, since a prefix filter never matches null.",
 				"required": false,
 				"type": "string",
 				"in": "body"
@@ -9795,7 +9981,7 @@ const routes = {
 			},
 			{
 				"name": "tags",
-				"description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter and knowledge search.",
+				"description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter and knowledge search.\n\nKeys beginning `system.` are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -9864,7 +10050,7 @@ const routes = {
 			},
 			{
 				"name": "tags",
-				"description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter and knowledge search.",
+				"description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter and knowledge search.\n\nKeys beginning `system.` are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -9971,7 +10157,7 @@ const routes = {
 			},
 			{
 				"name": "tags",
-				"description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter and knowledge search.",
+				"description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter and knowledge search.\n\nKeys beginning `system.` are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.",
 				"required": false,
 				"type": "object",
 				"in": "body"
@@ -11159,6 +11345,7 @@ const routes = {
 		httpMethod: "get",
 		pathParams: ["project_id"],
 		queryParams: [
+			"path_prefix",
 			"tags",
 			"limit",
 			"offset"
@@ -11173,6 +11360,13 @@ const routes = {
 				"type": "string",
 				"in": "path"
 			},
+			{
+				"name": "path_prefix",
+				"description": "Only files under this directory. The prefix is a path boundary, not a substring: `/reports` returns `/reports/q1.txt` and never `/reports-archive/q1.txt`, and `/` selects the whole project. A leading slash is optional and a trailing one is ignored, so `reports`, `/reports` and `/reports/` are the same filter. `%` and `_` are literal characters, not wildcards. Naming a directory under `/.system/` is what includes platform-written files, which a list without this parameter leaves out.",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
 			{
 				"name": "tags",
 				"description": "Filter by tag pairs, written `key:value` (split on the first colon, so a value may contain colons). Repeat the parameter for several pairs; **all** must be present with exactly that value.\n",
@@ -16290,7 +16484,7 @@ const routes = {
 			},
 			{
 				"name": "tags",
-				"description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter and knowledge search.",
+				"description": "Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with `400 VALIDATION_FAILED`, never coerced. Keys are opaque and stored verbatim, so `cost_center` and `costCenter` are two different tags. Matched by JSONB containment wherever tags are read: the `?tags=` filter and knowledge search.\n\nKeys beginning `system.` are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with `400 RESERVED_TAG_KEY`. They are read and filtered like any other tag.",
 				"required": false,
 				"type": "object",
 				"in": "body"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturali/cli",
-  "version": "0.132.0",
+  "version": "0.133.1",
   "description": "Command-line interface for the naturali.ai API, generated from its OpenAPI specs",
   "type": "module",
   "bin": {
@@ -21,10 +21,11 @@
     "access": "public"
   },
   "dependencies": {
-    "commander": "^15.0.0"
+    "commander": "^15.0.0",
+    "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@naturali/sdk": "0.132.0",
+    "@naturali/sdk": "0.133.1",
     "@ttoss/openapi-codegen": "^0.3.1",
     "@types/node": "^26.5.1",
     "tsdown": "^0.23.0",