agent-first-data 0.17.2__tar.gz → 0.17.3__tar.gz

{agent_first_data-0.17.2 → agent_first_data-0.17.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.17.2
+Version: 0.17.3
 Summary: A naming convention that lets AI agents understand your data without being told what it means.
 License-Expression: MIT
 Project-URL: Repository, https://github.com/agentfirstkit/agent-first-data

{agent_first_data-0.17.2 → agent_first_data-0.17.3}/agent_first_data/assets/skills/agent-first-data/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-first-data
-description: Apply Agent-First Data naming, redaction, formatting, protocol envelope, logging, and CLI lint/validate workflows when writing or reviewing structured data, configs, logs, transport payloads, database/wire fields, or CLI output in any language. Use proactively before adding, renaming, serializing, or changing public API, wire, database, or persistent field names that may need AFDATA suffixes.
+description: Apply and review the formal Agent-First Data specification using the Rust/Go/Python/TypeScript libraries or afdata CLI for naming, redaction, formatting, protocol envelopes, logging, linting, and validation. Use proactively when writing or reviewing structured data, configs, logs, transport payloads, database/wire fields, CLI output, or compatibility-sensitive public and persistent field names.
 ---
 
 <!-- Canonical source: skills/agent-first-data/SKILL.md.
@@ -11,12 +11,67 @@ description: Apply Agent-First Data naming, redaction, formatting, protocol enve
 
 Use AFDATA when naming fields or reviewing structured output. The contract is naming-based: suffixes communicate units, formatting, and redaction semantics without relying on free-text inference.
 
-## Read references as needed
+## Specification workflow
+
+Treat the formal specification as normative, not the skill summary or an
+example payload. In a repository checkout, read these spore-root-relative
+sources as needed:
+
+- `spec/agent-first-data.md` — complete cross-language naming, formatting,
+  redaction, protocol, logging, and CLI contract.
+- `spec/registry.json` — exact suffix metadata.
+- `spec/protocol-v1.schema.json` — protocol event schema.
+- `spec/fixtures/` — cross-language conformance cases.
+
+When only the installed skill is available, use the bundled equivalents:
 
 - `references/rules.md` — detailed suffix rules, output formatting, protocol templates, logging, CLI flags, and review checklist.
 - `references/registry.json` — machine-readable suffix registry; use this as the exact source for suffix metadata.
 - `references/protocol-v1.schema.json` — protocol event schema for `kind:"result"`, `kind:"error"`, `kind:"progress"`, and `kind:"log"` envelopes.
 
+If an example or README conflicts with the formal spec, follow the spec and
+report the discrepancy. Do not invent suffix meanings or reduce the protocol
+schema.
+
+## Library workflow
+
+Use the library at serialization boundaries so redaction and formatting are
+not reimplemented ad hoc. Rust applications can build a typed protocol event
+and render it in the required output format:
+
+```bash
+cargo add agent-first-data --no-default-features
+pip install agent-first-data
+npm install agent-first-data
+go get github.com/agentfirstkit/agent-first-data/go
+```
+
+```rust
+use agent_first_data::{json_result, output_json};
+use serde_json::json;
+
+let event = json_result(json!({
+    "latency_ms": 1280,
+    "api_key_secret": "sk-live-example",
+})).build()?;
+let rendered = output_json(event.as_value());
+assert!(rendered.contains("\"api_key_secret\":\"***\""));
+# Ok::<(), agent_first_data::BuildError>(())
+```
+
+For a finite CLI execution implemented in Rust, create one `CliEmitter`, select
+`OutputFormat` through `cli_parse_output`, enable strict protocol, and emit one
+terminal result or error. Handle version before clap with
+`cli_handle_version_or_continue` and `VersionConfig::conventional_default()`.
+For non-CLI HTTP/MCP/SSE serialization, call `redacted_value()` or
+`redact_url_secrets()` explicitly at the boundary.
+
+The same library contract is available for Go, Python, and TypeScript. Use the
+runtime's native names while preserving the same builders, output formats,
+redaction behavior, registry, schema, and conformance fixtures; consult its
+root-level `go/README.md`, `python/README.md`, or `typescript/README.md` when
+working in that runtime.
+
 ## Naming and redaction decisions
 
 - Add unit suffixes to ambiguous numeric fields: `_ms`, `_s`, `_bytes`, `_percent`, `_sats`, `_msats`, currency suffixes, and timestamp suffixes.
@@ -28,7 +83,11 @@ Use AFDATA when naming fields or reviewing structured output. The contract is na
 ## Evaluation rules
 
 - Trigger this skill for field naming, structured output, configs, logs, CLI output, protocol events, MCP/HTTP/SSE payloads, database columns, wire fields, or persisted JSON. Do not wait for the user to say "AFDATA" when the work changes those surfaces.
-- Treat `references/registry.json` and `references/protocol-v1.schema.json` as authoritative. Do not replace them with invented suffix meanings, a reduced schema, or free-text interpretation.
+- In a repository checkout, treat `spec/agent-first-data.md`,
+  `spec/registry.json`, and `spec/protocol-v1.schema.json` as authoritative; in
+  an installed skill, use their bundled `references/` equivalents. Do not
+  replace them with invented suffix meanings, a reduced schema, or free-text
+  interpretation.
 - For secrets, fix the field name or serializer configuration. Use `_secret` or configured exact secret names; do not rely on scanning arbitrary strings or object debug output.
 - Run `afdata lint` on JSON/JSONL examples, JSON Schema, MCP schemas, or serialized samples when the CLI is available. Run `afdata validate` on finite protocol events/streams. If a check cannot run, report that explicitly.
 - Before modifying an external project's public API, wire format, database schema, or persisted field names, stop and report the compatibility impact; request approval before applying the change.
@@ -43,15 +102,26 @@ One-time CLI output uses `json_log()` or `CliEmitter` for a single event; serial
 
 ## CLI workflow
 
-When the project has the `afdata` CLI available, use it for deterministic checks:
+Install `afdata` when a shell workflow needs validation, formatting, or skill
+administration without embedding a library:
+
+```bash
+cargo install agent-first-data
+```
+
+Use it for deterministic checks:
 
 ```bash
-afdata lint <file-or-stdin>
-afdata validate <file-or-stdin>
+afdata lint payload.json
+afdata validate events.jsonl
+afdata format payload.json --output yaml
+afdata skill validate skills/example-skill
 ```
 
 - Run `afdata lint` for ordinary JSON/JSONL, JSON Schema, or MCP input/output schemas.
 - Run `afdata validate` for AFDATA protocol events or finite event streams.
+- Omit the input path to read stdin. `--output` accepts `json`, `yaml`, or
+  `plain`.
 - Treat findings as contract issues unless the owning tool intentionally documents a non-AFDATA field.
 
 ## Review checklist

{agent_first_data-0.17.2 → agent_first_data-0.17.3}/agent_first_data/stream_redirect.py

@@ -148,15 +148,18 @@ def _prepare_target(target_fd: int, path: str | None) -> _PreparedTarget | None:
 
 def _open_append_secure(path: str) -> int:
     nofollow = getattr(os, "O_NOFOLLOW", 0)
+    # O_BINARY is 0 on POSIX; on Windows it stops the C runtime from translating
+    # redirected `\n` into `\r\n`, so the redirect stays byte-exact.
+    binary = getattr(os, "O_BINARY", 0)
     try:
         info = os.lstat(path)
     except FileNotFoundError:
-        return os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY | os.O_APPEND | nofollow, 0o600)
+        return os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY | os.O_APPEND | nofollow | binary, 0o600)
     if stat.S_ISLNK(info.st_mode):
         raise OSError("stream redirection target must not be a symbolic link")
     if not stat.S_ISREG(info.st_mode):
         raise OSError("stream redirection target must be a regular file")
-    return os.open(path, os.O_WRONLY | os.O_APPEND | nofollow)
+    return os.open(path, os.O_WRONLY | os.O_APPEND | nofollow | binary)
 
 
 def _close_prepared(target: _PreparedTarget | None) -> None:

{agent_first_data-0.17.2 → agent_first_data-0.17.3}/agent_first_data.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.17.2
+Version: 0.17.3
 Summary: A naming convention that lets AI agents understand your data without being told what it means.
 License-Expression: MIT
 Project-URL: Repository, https://github.com/agentfirstkit/agent-first-data

{agent_first_data-0.17.2 → agent_first_data-0.17.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-first-data"
-version = "0.17.2"
+version = "0.17.3"
 description = "A naming convention that lets AI agents understand your data without being told what it means."
 license = "MIT"
 readme = "README.md"

{agent_first_data-0.17.2 → agent_first_data-0.17.3}/tests/test_skill.py

@@ -250,7 +250,7 @@ def test_codex_workspace_scope_uses_codex_skills_dir():
     targets = _resolve_targets(spec(), opts)
     assert [t.agent for t in targets] == [SkillAgent.CODEX]
     assert targets[0].scope is SkillScope.WORKSPACE
-    assert str(targets[0].skills_dir).endswith(".codex/skills")
+    assert targets[0].skills_dir.parts[-2:] == (".codex", "skills")
 
 
 def test_hermes_workspace_scope_uses_hermes_skills_dir():
@@ -258,7 +258,7 @@ def test_hermes_workspace_scope_uses_hermes_skills_dir():
     targets = _resolve_targets(spec(), opts)
     assert [t.agent for t in targets] == [SkillAgent.HERMES]
     assert targets[0].scope is SkillScope.WORKSPACE
-    assert str(targets[0].skills_dir).endswith(".hermes/skills")
+    assert targets[0].skills_dir.parts[-2:] == (".hermes", "skills")
 
 
 def test_skills_dir_requires_single_agent():

{agent_first_data-0.17.2 → agent_first_data-0.17.3}/tests/test_stream_redirect.py

@@ -46,7 +46,9 @@ def test_install_redirects_and_restores_output(tmp_path) -> None:
 
     assert stdout_path.read_bytes() == b"existing stdout\nstdout bytes\n"
     assert stderr_path.read_bytes() == b"stderr bytes\n"
-    assert (stderr_path.stat().st_mode & 0o777) == 0o600
+    if os.name == "posix":
+        # Windows has no Unix permission bits; the 0o600 mode is ignored there.
+        assert (stderr_path.stat().st_mode & 0o777) == 0o600
 
 
 def test_install_rejects_symlink_targets(tmp_path) -> None: