artifact-contracts 0.30.2 → 0.31.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 foo-ogawa
+Copyright (c) 2026 foo-log-inc
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/cli-contract.yaml

@@ -12,8 +12,8 @@ info:
   license:
     name: MIT
   contact:
-    name: foo-ogawa
-    url: https://github.com/foo-ogawa/artifact-contracts
+    name: foo-log-inc
+    url: https://github.com/foo-log-inc/artifact-contracts
 
 artifact_slots:
   artifact-definitions:

package/docs/cli-reference.md

@@ -0,0 +1,252 @@
+# artifact-contracts CLI
+
+Declarative artifact registry — define file properties, resolve paths to artifact IDs, and detect definition overlaps. stdout is reserved for primary output (JSON/YAML/text result); all diagnostics and progress messages go to stderr.
+
+**Version:** 0.1.1
+
+## Table of Contents
+
+- [artifact-contracts](#artifact-contracts)
+  - [validate](#artifact-contracts-validate)
+  - [resolve](#artifact-contracts-resolve)
+  - [list](#artifact-contracts-list)
+  - [explain](#artifact-contracts-explain)
+  - [audit](#artifact-contracts-audit)
+
+---
+
+## artifact-contracts
+
+Artifact registry CLI — validate definitions, resolve artifacts, list registered entries, and explain file properties.
+
+### Global Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--version` | -V | No |  | Output the version number |
+| `--help` | -h | No |  | Display help for command |
+
+### Environment Variables
+
+| Variable | Description |
+|---|---|
+| `OPENAI_API_KEY` | OpenAI API key. Required when --adapter openai is selected. |
+| `ANTHROPIC_API_KEY` | Anthropic API key. Required when --adapter claude is selected. |
+| `GEMINI_API_KEY` | Google Gemini API key. Required when --adapter gemini is selected. |
+| `CURSOR_API_KEY` | Cursor API key. Required when --adapter cursor is selected. |
+
+### validate
+
+Validate artifact-contracts definitions
+
+Validates artifact-contracts.yaml against the schema, checks artifact ID naming conventions, ensures path_patterns are non-empty, and optionally detects overlapping definitions against real repository files.
+
+**Usage:**
+
+```
+artifact-contracts validate [--config] [--check-files]
+```
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` |  | No |  | Path to artifact-contracts.config.yaml |
+| `--check-files` |  | No |  | Scan repository files to detect path_patterns overlaps that static glob analysis cannot fully determine. When enabled, reads all files from git ls-files or glob. |
+
+#### Exit Codes
+
+**Exit 0:** Validation passed with no errors
+
+**Exit 1:** Schema or naming convention errors detected
+
+**Exit 2:** Overlap detected — same path matches multiple artifacts
+
+**Exit 3:** Config or input file not found / parse error
+
+#### Extensions
+
+```yaml
+x-agent: 
+  expected_duration_ms: 5000
+  retryable_exit_codes: 
+
+```
+
+---
+
+### resolve
+
+Output fully-resolved artifact definitions
+
+Expands config variables, applies authority-based defaults for manual_edit and change_control, and outputs the complete resolved DSL. Default format is yaml.
+
+**Usage:**
+
+```
+artifact-contracts resolve [--config] [--format]
+```
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` |  | No |  | Path to artifact-contracts.config.yaml |
+| `--format` |  | No |  | Output format (default: yaml) |
+
+#### Exit Codes
+
+**Exit 0:** Successfully output resolved definitions
+
+**Exit 1:** Error resolving definitions
+
+**Exit 3:** Config or input file not found / parse error
+
+#### Extensions
+
+```yaml
+x-agent: 
+  expected_duration_ms: 2000
+  retryable_exit_codes: 
+
+```
+
+---
+
+### list
+
+List registered artifacts
+
+Displays all registered artifacts with optional filtering by authority. Use --path for simple ID lookup; use explain for full governance metadata. Default format is text.
+
+**Usage:**
+
+```
+artifact-contracts list [--config] [--authority] [--path] [--format]
+```
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` |  | No |  | Path to artifact-contracts.config.yaml |
+| `--authority` |  | No |  | Filter by authority type |
+| `--path` |  | No |  | Reverse-lookup — show artifact IDs matching this file path. For full governance details, use the explain command. |
+| `--format` |  | No |  | Output format (default: text) |
+
+#### Exit Codes
+
+**Exit 0:** Successfully listed artifacts
+
+**Exit 1:** Error reading definitions
+
+**Exit 3:** Config or input file not found / parse error
+
+#### Extensions
+
+```yaml
+x-agent: 
+  expected_duration_ms: 2000
+  retryable_exit_codes: 
+
+```
+
+---
+
+### explain
+
+Explain artifact properties for a file path
+
+Given a file path, resolves the matching artifact and displays its full governance properties — artifact ID, authority, manual_edit policy, change_control, and other metadata. Useful for humans and LLM agents to understand file governance. Default format is text.
+
+**Usage:**
+
+```
+artifact-contracts explain <path> [--config] [--format]
+```
+
+#### Arguments
+
+| Name | Required | Description |
+|---|---|---|
+| `path` | Yes | File path to explain |
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` |  | No |  | Path to artifact-contracts.config.yaml |
+| `--format` |  | No |  | Output format (default: text) |
+
+#### Exit Codes
+
+**Exit 0:** Path resolved to an artifact
+
+**Exit 2:** Overlap — path matches multiple artifacts
+
+**Exit 3:** Config or input file not found / parse error
+
+**Exit 4:** Path does not match any registered artifact
+
+#### Extensions
+
+```yaml
+x-agent: 
+  expected_duration_ms: 2000
+  retryable_exit_codes: 
+
+```
+
+---
+
+### audit
+
+LLM-based semantic audit of artifact definitions
+
+Performs semantic analysis of artifact definitions using LLM to identify quality issues that static validation cannot detect — naming inconsistencies, missing coverage for common file types, authority mismatches, and structural improvements.
+
+**Usage:**
+
+```
+artifact-contracts audit [--config] [--adapter] [--model] [--show-prompt] [--dry-run] [--fail-on] [--output] [--report-format]
+```
+
+#### Options
+
+| Option | Aliases | Required | Default | Description |
+|---|---|---|---|---|
+| `--config` |  | No |  | Path to artifact-contracts.config.yaml |
+| `--adapter` |  | No |  | LLM adapter to use |
+| `--model` |  | No |  | Model name to pass to the adapter |
+| `--show-prompt` |  | No |  | Output the constructed prompt without calling the LLM API |
+| `--dry-run` | -n | No |  | Alias for --show-prompt (output prompt without LLM call) |
+| `--fail-on` |  | No |  | Minimum severity that causes exit 10. Ordering: critical > error > warning > info. For example, --fail-on warning exits 10 on warning, error, or critical. |
+| `--output` | -o | No |  | Write result to a file instead of stdout |
+| `--report-format` |  | No |  | Output format for the report (default: text). LLM commands use --report-format; deterministic commands use --format. |
+
+#### Exit Codes
+
+**Exit 0:** Audit completed — no findings above threshold
+
+**Exit 1:** General / transient error
+
+**Exit 3:** Config or input file not found / parse error
+
+**Exit 10:** Findings detected above --fail-on threshold
+
+**Exit 11:** agent-contracts-runtime is not installed
+
+**Exit 12:** Adapter initialization error (missing API key, etc.)
+
+#### Extensions
+
+```yaml
+x-agent: 
+  expected_duration_ms: 120000
+  retryable_exit_codes: 
+    - 1
+  recommended_before_use: 
+    - Run with --show-prompt first to preview the prompt
+```
+
+---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "artifact-contracts",
-  "version": "0.30.2",
+  "version": "0.31.0",
   "description": "Declarative artifact registry — define file properties, resolve paths to artifact IDs, and detect definition overlaps",
   "type": "module",
   "main": "dist/index.js",
@@ -21,6 +21,7 @@
   "files": [
     "dist",
     "schemas",
+    "docs",
     "cli-contract.yaml",
     "README.md",
     "LICENSE"
@@ -44,15 +45,15 @@
     "registry",
     "validation"
   ],
-  "author": "foo-ogawa",
+  "author": "foo-log-inc",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/foo-ogawa/artifact-contracts.git"
+    "url": "git+https://github.com/foo-log-inc/artifact-contracts.git"
   },
-  "homepage": "https://github.com/foo-ogawa/artifact-contracts#readme",
+  "homepage": "https://github.com/foo-log-inc/artifact-contracts#readme",
   "bugs": {
-    "url": "https://github.com/foo-ogawa/artifact-contracts/issues"
+    "url": "https://github.com/foo-log-inc/artifact-contracts/issues"
   },
   "dependencies": {
     "commander": "^12.1.0",
@@ -81,7 +82,7 @@
     "cli-contracts": "^0.30.0",
     "tsx": "^4.19.0",
     "typescript": "^6.0.2",
-    "vitest": "^2.0.0"
+    "vitest": "^4.1.7"
   },
   "engines": {
     "node": ">=20.0.0"

package/schemas/2026A.config.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/foo-ogawa/artifact-contracts/schemas/2026A.config.json",
+  "$id": "https://github.com/foo-log-inc/artifact-contracts/schemas/2026A.config.json",
   "title": "Artifact Contracts Config",
   "description": "Schema for artifact-contracts.config.yaml — processing configuration and variables.",
   "version": "2026A",

package/schemas/2026A.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/foo-ogawa/artifact-contracts/schemas/2026A.json",
+  "$id": "https://github.com/foo-log-inc/artifact-contracts/schemas/2026A.json",
   "title": "Artifact Contracts Document",
   "description": "Schema for artifact-contracts.yaml — declarative artifact registry definitions.",
   "version": "2026A",