agent-first-data 0.26.2 → 0.28.0

package/README.md

@@ -17,7 +17,7 @@ console.log(render(event.toJSON(), "json"));
 console.log(render(event.toJSON(), "plain"));
 ```
 
-Useful names use TypeScript casing: `render`, `outputOptionsForPolicy`, `redactedValue`, `redactUrlSecrets`, `redactArgv`, `normalizeUtcOffset`, `isValidRfc3339Date`, `isValidRfc3339Time`, `isValidRfc3339`, `isValidBcp47`, `decodeProtocolEvent`, `cliParseOutput`, `cliParseLogFilters`, `buildCliError`, `buildCliVersion`, and `cliHandleVersionOrContinue`.
+Useful names use TypeScript casing: `render`, `outputOptionsForPolicy`, `redactedValue`, `redactUrlSecrets`, `redactArgv`, `normalizeUtcOffset`, `isValidRfc3339Date`, `isValidRfc3339Time`, `isValidRfc3339`, `isValidBcp47`, `decodeProtocolEvent`, `cliParseOutput`, `cliParseLogFilters`, `buildCliError`, and `buildCliVersion`.
 
 ## Behavior Notes
 
@@ -26,7 +26,7 @@ Useful names use TypeScript casing: `render`, `outputOptionsForPolicy`, `redacte
 - YAML keeps original keys and values (structure-preserving, like JSON), sorting keys by UTF-16 code unit order and quoting/escaping unsafe keys and string scalars. Plain strips formatting suffixes, formats values, sorts the same way, and renders nested objects/arrays as canonical JSON.
 - Logging records use `kind:"log"` with a nested `log` payload and a separate `level` field, so error-level logs are not terminal protocol errors.
 - `buildCliError(message, hint?)` returns a strict-ready CLI error with `error.retryable:false` and `trace:{}`.
-- Use `cliHandleVersionOrContinue()` before argument parsing so `--version` always answers with a structured protocol-v1 `kind:"result"` version event. An explicit `--output` wins; pass the command's normal output as `defaultOutput` (JSON when omitted), plus its value-taking global flag names.
+- Do not add a raw version/help pre-parser. Until the TypeScript `CliSpec` compiler lands, applications should keep lifecycle parsing in their own parser rather than claim AFDATA closed-world help compatibility.
 
 ## Reference
 

package/assets/cli-help-v2.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentfirstkit.org/schemas/agent-first-data/cli-help-v2.schema.json",
+  "title": "AFDATA CLI help v2 event",
+  "description": "One command's complete invocation help, carried by an AFDATA result event. Domain outcomes, side effects, and runtime error catalogs remain in the owning tool's documentation.",
+  "type": "object",
+  "required": [
+    "kind",
+    "result",
+    "trace"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "kind": {
+      "const": "result"
+    },
+    "result": {
+      "type": "object",
+      "required": [
+        "code",
+        "help"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "code": {
+          "const": "help"
+        },
+        "help": {
+          "$ref": "#/$defs/help"
+        }
+      }
+    },
+    "trace": {
+      "type": "object"
+    }
+  },
+  "$defs": {
+    "oneLine": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[^\\n\\r]+$"
+    },
+    "nonEmptyStringMap": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "help": {
+      "type": "object",
+      "required": [
+        "schema",
+        "command_path"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "schema": {
+          "const": "cli-help-v2"
+        },
+        "command_path": {
+          "$ref": "#/$defs/oneLine"
+        },
+        "about": {
+          "$ref": "#/$defs/oneLine"
+        },
+        "shapes": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/shape"
+          },
+          "description": "Every legal shape of this command, each complete. Help answers in one round trip; a second level could only pay off by omitting the optional arguments, which would then be undiscoverable."
+        },
+        "subcommands": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/oneLine"
+          }
+        },
+        "notes": {
+          "$ref": "#/$defs/nonEmptyStringMap",
+          "description": "Argument meanings. Arguments belong to the command rather than to one shape, so they are stated once."
+        },
+        "defaults": {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": true
+        }
+      }
+    },
+    "shape": {
+      "type": "object",
+      "required": [
+        "id",
+        "usage"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/oneLine"
+        },
+        "about": {
+          "$ref": "#/$defs/oneLine",
+          "description": "How this shape differs from its siblings. Absent when the command has only one shape, because its own description already covers it."
+        },
+        "usage": {
+          "$ref": "#/$defs/oneLine"
+        }
+      }
+    }
+  }
+}

package/assets/cli-spec-v1.schema.json

@@ -0,0 +1,334 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentfirstkit.org/schemas/agent-first-data/cli-spec-v1.schema.json",
+  "title": "AFDATA closed-world CLI spec v1",
+  "type": "object",
+  "required": [
+    "schema",
+    "name",
+    "version",
+    "lifecycle_output",
+    "commands"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema": {
+      "const": "cli-spec-v1"
+    },
+    "name": {
+      "$ref": "#/$defs/nonEmpty"
+    },
+    "version": {
+      "$ref": "#/$defs/nonEmpty"
+    },
+    "display_name": {
+      "$ref": "#/$defs/nonEmpty",
+      "description": "Human-facing product name, distinct from the binary identity in `name`."
+    },
+    "build": {
+      "$ref": "#/$defs/nonEmpty",
+      "description": "Opaque build identifier, such as a git commit SHA. Its meaning is the host's."
+    },
+    "about": {
+      "$ref": "#/$defs/nonEmpty"
+    },
+    "lifecycle_output": {
+      "$ref": "#/$defs/output"
+    },
+    "commands": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/command"
+      }
+    }
+  },
+  "$defs": {
+    "nonEmpty": {
+      "type": "string",
+      "minLength": 1
+    },
+    "argumentId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*$"
+    },
+    "command": {
+      "type": "object",
+      "required": [
+        "command_path",
+        "arguments",
+        "combinations"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "command_path": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$"
+          }
+        },
+        "about": {
+          "$ref": "#/$defs/nonEmpty"
+        },
+        "arguments": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/argument"
+          }
+        },
+        "combinations": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/combination"
+          }
+        }
+      }
+    },
+    "argument": {
+      "type": "object",
+      "required": [
+        "argument_id",
+        "syntax",
+        "value_type"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "argument_id": {
+          "$ref": "#/$defs/argumentId"
+        },
+        "syntax": {
+          "oneOf": [
+            {
+              "type": "object",
+              "required": [
+                "kind",
+                "name"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "kind": {
+                  "const": "long"
+                },
+                "name": {
+                  "type": "string",
+                  "pattern": "^--[a-z0-9][a-z0-9-]*$"
+                }
+              }
+            },
+            {
+              "type": "object",
+              "required": [
+                "kind",
+                "index"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "kind": {
+                  "const": "positional"
+                },
+                "index": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              }
+            }
+          ]
+        },
+        "value_type": {
+          "enum": [
+            "flag",
+            "string",
+            "i64",
+            "finite_f64",
+            "enum",
+            "json"
+          ]
+        },
+        "value_name": {
+          "$ref": "#/$defs/nonEmpty"
+        },
+        "enum_values": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/nonEmpty"
+          }
+        },
+        "default": true,
+        "repeatable": {
+          "const": true
+        },
+        "sensitive": {
+          "type": "boolean",
+          "description": "This argument's value must never be echoed back in help, errors, or logs."
+        },
+        "about": {
+          "$ref": "#/$defs/nonEmpty"
+        }
+      }
+    },
+    "combination": {
+      "type": "object",
+      "required": [
+        "combination_id",
+        "action_id",
+        "output"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "combination_id": {
+          "$ref": "#/$defs/nonEmpty"
+        },
+        "action_id": {
+          "$ref": "#/$defs/nonEmpty"
+        },
+        "about": {
+          "$ref": "#/$defs/nonEmpty"
+        },
+        "fixed": {
+          "type": "object",
+          "additionalProperties": {
+            "oneOf": [
+              {
+                "$ref": "#/$defs/nonEmpty"
+              },
+              {
+                "type": "object",
+                "required": [
+                  "one_of"
+                ],
+                "additionalProperties": false,
+                "properties": {
+                  "one_of": {
+                    "type": "array",
+                    "minItems": 1,
+                    "uniqueItems": true,
+                    "items": {
+                      "$ref": "#/$defs/nonEmpty"
+                    }
+                  }
+                }
+              }
+            ]
+          }
+        },
+        "required": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/argumentId"
+          }
+        },
+        "optional": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/$defs/argumentId"
+          }
+        },
+        "output": {
+          "$ref": "#/$defs/output"
+        }
+      }
+    },
+    "fileSinks": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "stdout",
+          "stderr"
+        ]
+      }
+    },
+    "output": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "kind",
+            "file_sinks"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "const": "raw"
+            },
+            "file_sinks": {
+              "$ref": "#/$defs/fileSinks"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "kind",
+            "lifecycle",
+            "formats",
+            "destinations",
+            "default_format",
+            "default_destination",
+            "file_sinks"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "const": "protocol"
+            },
+            "lifecycle": {
+              "enum": [
+                "finite",
+                "stream"
+              ]
+            },
+            "formats": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "enum": [
+                  "json",
+                  "yaml",
+                  "plain"
+                ]
+              }
+            },
+            "destinations": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "enum": [
+                  "split",
+                  "stdout",
+                  "stderr"
+                ]
+              }
+            },
+            "default_format": {
+              "enum": [
+                "json",
+                "yaml",
+                "plain"
+              ]
+            },
+            "default_destination": {
+              "enum": [
+                "split",
+                "stdout",
+                "stderr"
+              ]
+            },
+            "file_sinks": {
+              "$ref": "#/$defs/fileSinks"
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/assets/protocol-v1.schema.json

@@ -1,67 +1,178 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://agentfirstkit.org/schemas/agent-first-data/protocol-v1.schema.json",
-  "title": "Agent-First Data Protocol v1 Event",
-  "type": "object",
-  "oneOf": [
-    {"$ref": "#/$defs/resultEvent"},
-    {"$ref": "#/$defs/errorEvent"},
-    {"$ref": "#/$defs/progressEvent"},
-    {"$ref": "#/$defs/logEvent"}
-  ],
+  "title": "Agent-First Data Protocol v1 Event (base profile)",
+  "description": "One protocol v1 event. The document root is the BASE profile: the mandatory MUST rules only — envelope shape and error payload requirements. Validate against the root unless you are claiming strict conformance; rejecting a base-conformant event is a false negative. The STRICT profile is `#/$defs/strictEvent`: it additionally requires the two recommendations (an object `trace` on every event, a boolean `error.retryable`). Stream lifecycle — (log | progress)* then exactly one result | error — is not expressible per event; validate a whole stream with `afdata validate` or `validate_protocol_stream`.",
+  "$ref": "#/$defs/event",
   "$defs": {
+    "event": {
+      "title": "Protocol v1 event, base profile",
+      "description": "Top-level fields are closed: `kind`, the payload field whose name equals `kind`, and an optional `trace`.",
+      "type": "object",
+      "oneOf": [
+        {
+          "$ref": "#/$defs/resultEvent"
+        },
+        {
+          "$ref": "#/$defs/errorEvent"
+        },
+        {
+          "$ref": "#/$defs/progressEvent"
+        },
+        {
+          "$ref": "#/$defs/logEvent"
+        }
+      ]
+    },
+    "strictEvent": {
+      "title": "Protocol v1 event, strict profile",
+      "description": "The base profile plus the recommendations of the spec's `Validation profiles` section. Equivalent to `validate_protocol_event(event, strict = true)`.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/event"
+        },
+        {
+          "$ref": "#/$defs/strictRecommendations"
+        }
+      ]
+    },
+    "strictRecommendations": {
+      "description": "What the strict profile adds on top of the base profile, and nothing else.",
+      "type": "object",
+      "required": [
+        "trace"
+      ],
+      "properties": {
+        "trace": {
+          "$ref": "#/$defs/trace"
+        }
+      },
+      "if": {
+        "type": "object",
+        "properties": {
+          "kind": {
+            "const": "error"
+          }
+        },
+        "required": [
+          "kind"
+        ]
+      },
+      "then": {
+        "properties": {
+          "error": {
+            "type": "object",
+            "required": [
+              "retryable"
+            ],
+            "properties": {
+              "retryable": {
+                "type": "boolean"
+              }
+            }
+          }
+        }
+      }
+    },
     "trace": {
+      "description": "Execution context. Recommended on every event, required by the strict profile. Its fields are owned by the emitting tool.",
       "type": "object"
     },
     "resultEvent": {
       "type": "object",
       "properties": {
-        "kind": {"const": "result"},
+        "kind": {
+          "const": "result"
+        },
         "result": true,
-        "trace": {"$ref": "#/$defs/trace"}
+        "trace": {
+          "$ref": "#/$defs/trace"
+        }
       },
-      "required": ["kind", "result"],
+      "required": [
+        "kind",
+        "result"
+      ],
       "additionalProperties": false
     },
     "errorEvent": {
       "type": "object",
       "properties": {
-        "kind": {"const": "error"},
+        "kind": {
+          "const": "error"
+        },
         "error": {
-          "type": "object",
-          "properties": {
-            "code": {"type": "string", "minLength": 1},
-            "message": {"type": "string", "minLength": 1},
-            "retryable": {"type": "boolean"},
-            "hint": {"type": "string"}
-          },
-          "required": ["code", "message", "retryable"],
-          "additionalProperties": true
+          "$ref": "#/$defs/errorPayload"
         },
-        "trace": {"$ref": "#/$defs/trace"}
+        "trace": {
+          "$ref": "#/$defs/trace"
+        }
       },
-      "required": ["kind", "error"],
+      "required": [
+        "kind",
+        "error"
+      ],
       "additionalProperties": false
     },
     "progressEvent": {
       "type": "object",
       "properties": {
-        "kind": {"const": "progress"},
+        "kind": {
+          "const": "progress"
+        },
         "progress": true,
-        "trace": {"$ref": "#/$defs/trace"}
+        "trace": {
+          "$ref": "#/$defs/trace"
+        }
       },
-      "required": ["kind", "progress"],
+      "required": [
+        "kind",
+        "progress"
+      ],
       "additionalProperties": false
     },
     "logEvent": {
       "type": "object",
       "properties": {
-        "kind": {"const": "log"},
+        "kind": {
+          "const": "log"
+        },
         "log": true,
-        "trace": {"$ref": "#/$defs/trace"}
+        "trace": {
+          "$ref": "#/$defs/trace"
+        }
       },
-      "required": ["kind", "log"],
+      "required": [
+        "kind",
+        "log"
+      ],
       "additionalProperties": false
+    },
+    "errorPayload": {
+      "description": "Extension fields go directly on this object; there is no `details` wrapper.",
+      "type": "object",
+      "properties": {
+        "code": {
+          "type": "string",
+          "minLength": 1
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1
+        },
+        "hint": {
+          "description": "Actionable remediation. Omit it when there is none.",
+          "type": "string"
+        },
+        "retryable": {
+          "description": "Whether retrying the same call can succeed. Recommended, and left unconstrained by the base profile — the strict profile (`#/$defs/strictEvent`) requires it and requires a boolean."
+        }
+      },
+      "required": [
+        "code",
+        "message"
+      ],
+      "additionalProperties": true
     }
   }
 }