specfact-cli 0.4.2__py3-none-any.whl → 0.6.8__py3-none-any.whl

specfact_cli/resources/schemas/plan.schema.json

@@ -0,0 +1,204 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Plan Bundle Schema",
+  "description": "Schema for SpecFact CLI plan bundle validation",
+  "type": "object",
+  "required": ["version", "product"],
+  "properties": {
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$",
+      "description": "Plan bundle version"
+    },
+    "idea": {
+      "type": "object",
+      "required": ["title", "narrative"],
+      "properties": {
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "narrative": {
+          "type": "string",
+          "minLength": 1
+        },
+        "target_users": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "value_hypothesis": {
+          "type": "string"
+        },
+        "constraints": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "metrics": {
+          "type": "object"
+        }
+      }
+    },
+    "business": {
+      "type": "object",
+      "properties": {
+        "segments": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "problems": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "solutions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "differentiation": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "risks": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "product": {
+      "type": "object",
+      "required": ["themes"],
+      "properties": {
+        "themes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "releases": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "objectives": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "scope": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "risks": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "features": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["key", "title"],
+        "properties": {
+          "key": {
+            "type": "string",
+            "pattern": "^FEATURE-\\d+$"
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1
+          },
+          "outcomes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "acceptance": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "constraints": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "stories": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["key", "title"],
+              "properties": {
+                "key": {
+                  "type": "string",
+                  "pattern": "^STORY-\\d+$"
+                },
+                "title": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "acceptance": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "tags": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "confidence": {
+                  "type": "number",
+                  "minimum": 0.0,
+                  "maximum": 1.0
+                },
+                "draft": {
+                  "type": "boolean"
+                }
+              }
+            }
+          },
+          "confidence": {
+            "type": "number",
+            "minimum": 0.0,
+            "maximum": 1.0
+          },
+          "draft": {
+            "type": "boolean"
+          }
+        }
+      }
+    }
+  }
+}
+

specfact_cli/resources/schemas/protocol.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Protocol Schema",
+  "description": "Schema for SpecFact CLI FSM protocol validation",
+  "type": "object",
+  "required": ["states", "start", "transitions"],
+  "properties": {
+    "states": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1,
+      "uniqueItems": true,
+      "description": "List of state names"
+    },
+    "start": {
+      "type": "string",
+      "description": "Initial state name"
+    },
+    "transitions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["from_state", "on_event", "to_state"],
+        "properties": {
+          "from_state": {
+            "type": "string"
+          },
+          "on_event": {
+            "type": "string"
+          },
+          "to_state": {
+            "type": "string"
+          },
+          "guard": {
+            "type": "string",
+            "description": "Guard function name"
+          }
+        }
+      },
+      "description": "List of state transitions"
+    },
+    "guards": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "Guard definitions"
+    }
+  }
+}
+

specfact_cli/resources/templates/github-action.yml.j2

@@ -0,0 +1,140 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
+# yamllint disable rule:line-length rule:truthy
+name: SpecFact CLI Validation
+
+on:
+  pull_request:
+    branches: [main, dev]
+    paths-ignore:
+      - "docs/**"
+      - "**.md"
+      - "**.mdc"
+  push:
+    branches: [main, dev]
+    paths-ignore:
+      - "docs/**"
+      - "**.md"
+      - "**.mdc"
+  workflow_dispatch:
+    inputs:
+      budget:
+        description: "Time budget in seconds"
+        required: false
+        default: "{{ budget }}"
+        type: string
+      mode:
+        description: "Enforcement mode (block, warn, log)"
+        required: false
+        default: "block"
+        type: choice
+        options:
+          - block
+          - warn
+          - log
+
+jobs:
+  specfact-validation:
+    name: Contract Validation
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      checks: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "{{ python_version }}"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install hatch
+
+      - name: Install SpecFact CLI
+        run: |
+          echo "📦 Installing SpecFact CLI..."
+          pip install specfact-cli
+
+      - name: Set validation parameters
+        id: validation
+        run: |
+          BUDGET="${INPUT_BUDGET:-{{ budget }}}"
+          MODE="${INPUT_MODE:-block}"
+          echo "budget=$BUDGET" >> $GITHUB_OUTPUT
+          echo "mode=$MODE" >> $GITHUB_OUTPUT
+          echo "SPECFACT_BUDGET=$BUDGET" >> $GITHUB_ENV
+          echo "SPECFACT_MODE=$MODE" >> $GITHUB_ENV
+
+      - name: Run Contract Validation
+        id: repro
+        continue-on-error: true
+        run: |
+          specfact repro --verbose --budget {% raw %}${{ steps.validation.outputs.budget }}{% endraw %} || true
+          echo "exit_code=$?" >> $GITHUB_OUTPUT
+
+      - name: Find latest repro report
+        id: report
+        if: always()
+        run: |
+          REPORT_DIR=".specfact/reports/enforcement"
+          if [ -d "$REPORT_DIR" ]; then
+            LATEST_REPORT=$(find "$REPORT_DIR" -name "report-*.yaml" -type f -printf "%T@ %p\n" | sort -n | tail -1 | cut -d' ' -f2-)
+            if [ -n "$LATEST_REPORT" ]; then
+              echo "path=$LATEST_REPORT" >> $GITHUB_OUTPUT
+              echo "SPECFACT_REPORT_PATH=$LATEST_REPORT" >> $GITHUB_ENV
+            fi
+          fi
+
+      - name: Create GitHub annotations
+        id: annotations
+        if: always() && {% raw %}steps.report.outputs.path != ''{% endraw %}
+        run: |
+          python -m specfact_cli.utils.github_annotations || true
+
+      - name: Generate PR comment
+        id: pr-comment
+        if: always() && {% raw %}github.event_name == 'pull_request' && steps.report.outputs.path != ''{% endraw %}
+        run: |
+          python -m specfact_cli.utils.github_annotations
+          if [ -f ".specfact/pr-comment.md" ]; then
+            echo "comment_path=.specfact/pr-comment.md" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Post PR comment
+        if: always() && {% raw %}github.event_name == 'pull_request' && steps.pr-comment.outputs.comment_path != ''{% endraw %}
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const commentPath = '{% raw %}${{ steps.pr-comment.outputs.comment_path }}{% endraw %}';
+            if (fs.existsSync(commentPath)) {
+              const comment = fs.readFileSync(commentPath, 'utf8');
+              github.rest.issues.createComment({
+                issue_number: context.issue.number,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                body: comment
+              });
+            }
+
+      - name: Upload validation report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: specfact-report
+          path: |
+            .specfact/reports/enforcement/*.yaml
+            .specfact/pr-comment.md
+          if-no-files-found: ignore
+
+      - name: Fail workflow if validation failed
+        if: {% raw %}steps.repro.outputs.exit_code != '0' && steps.validation.outputs.mode == 'block'{% endraw %}
+        run: |
+          echo "❌ Validation failed. Exiting with error code."
+          exit 1
+

specfact_cli/resources/templates/plan.bundle.yaml.j2

@@ -0,0 +1,141 @@
+version: "1.0"
+
+{% if idea %}
+idea:
+  title: {{ idea.title }}
+  narrative: {{ idea.narrative }}
+  {% if idea.target_users %}
+  target_users:
+  {% for user in idea.target_users %}
+    - {{ user }}
+  {% endfor %}
+  {% endif %}
+  {% if idea.value_hypothesis %}
+  value_hypothesis: {{ idea.value_hypothesis }}
+  {% endif %}
+  {% if idea.constraints %}
+  constraints:
+  {% for constraint in idea.constraints %}
+    - {{ constraint }}
+  {% endfor %}
+  {% endif %}
+  {% if idea.metrics %}
+  metrics: {{ idea.metrics | tojson }}
+  {% endif %}
+{% endif %}
+
+{% if business %}
+business:
+  {% if business.segments %}
+  segments:
+  {% for segment in business.segments %}
+    - {{ segment }}
+  {% endfor %}
+  {% endif %}
+  {% if business.problems %}
+  problems:
+  {% for problem in business.problems %}
+    - {{ problem }}
+  {% endfor %}
+  {% endif %}
+  {% if business.solutions %}
+  solutions:
+  {% for solution in business.solutions %}
+    - {{ solution }}
+  {% endfor %}
+  {% endif %}
+  {% if business.differentiation %}
+  differentiation:
+  {% for diff in business.differentiation %}
+    - {{ diff }}
+  {% endfor %}
+  {% endif %}
+  {% if business.risks %}
+  risks:
+  {% for risk in business.risks %}
+    - {{ risk }}
+  {% endfor %}
+  {% endif %}
+{% endif %}
+
+product:
+  {% if product.themes %}
+  themes:
+  {% for theme in product.themes %}
+    - {{ theme }}
+  {% endfor %}
+  {% endif %}
+  {% if product.releases %}
+  releases:
+  {% for release in product.releases %}
+    - name: {{ release.name }}
+      {% if release.objectives %}
+      objectives:
+      {% for objective in release.objectives %}
+        - {{ objective }}
+      {% endfor %}
+      {% endif %}
+      {% if release.scope %}
+      scope:
+      {% for item in release.scope %}
+        - {{ item }}
+      {% endfor %}
+      {% endif %}
+      {% if release.risks %}
+      risks:
+      {% for risk in release.risks %}
+        - {{ risk }}
+      {% endfor %}
+      {% endif %}
+  {% endfor %}
+  {% endif %}
+
+{% if features %}
+features:
+{% for feature in features %}
+  - key: {{ feature.key }}
+    title: {{ feature.title }}
+    {% if feature.outcomes %}
+    outcomes:
+    {% for outcome in feature.outcomes %}
+      - {{ outcome }}
+    {% endfor %}
+    {% endif %}
+    {% if feature.acceptance %}
+    acceptance:
+    {% for criterion in feature.acceptance %}
+      - {{ criterion }}
+    {% endfor %}
+    {% endif %}
+    {% if feature.constraints %}
+    constraints:
+    {% for constraint in feature.constraints %}
+      - {{ constraint }}
+    {% endfor %}
+    {% endif %}
+    {% if feature.stories %}
+    stories:
+    {% for story in feature.stories %}
+      - key: {{ story.key }}
+        title: {{ story.title }}
+        {% if story.acceptance %}
+        acceptance:
+        {% for criterion in story.acceptance %}
+          - {{ criterion }}
+        {% endfor %}
+        {% endif %}
+        {% if story.tags %}
+        tags:
+        {% for tag in story.tags %}
+          - {{ tag }}
+        {% endfor %}
+        {% endif %}
+        confidence: {{ story.confidence }}
+        draft: {{ story.draft | lower }}
+    {% endfor %}
+    {% endif %}
+    confidence: {{ feature.confidence }}
+    draft: {{ feature.draft | lower }}
+{% endfor %}
+{% endif %}
+

specfact_cli/resources/templates/pr-template.md.j2

@@ -0,0 +1,58 @@
+## 🎯 Purpose
+
+{{ purpose | default("Describe the purpose of this PR") }}
+
+## 📋 Changes
+
+{% if changes %}
+{% for change in changes %}
+- {{ change }}
+{% endfor %}
+{% else %}
+- [ ] List your changes here
+{% endif %}
+
+## ✅ Validation
+
+**SpecFact CLI Validation Results:**
+
+{% if validation_passed %}
+- ✅ All contracts validated successfully
+- ✅ No plan deviations detected
+- ✅ FSM protocol compliant
+{% else %}
+- ⚠️ Validation findings:
+{% if high_count > 0 %}
+  - {{ high_count }} HIGH severity issue(s)
+{% endif %}
+{% if medium_count > 0 %}
+  - {{ medium_count }} MEDIUM severity issue(s)
+{% endif %}
+{% if low_count > 0 %}
+  - {{ low_count }} LOW severity issue(s)
+{% endif %}
+{% endif %}
+
+## 📊 Coverage
+
+{% if coverage %}
+- **Line Coverage**: {{ coverage.line }}%
+- **Branch Coverage**: {{ coverage.branch }}%
+{% else %}
+- [ ] Add coverage information
+{% endif %}
+
+## 🔗 Related
+
+{% if related_issues %}
+{% for issue in related_issues %}
+- Closes #{{ issue }}
+{% endfor %}
+{% else %}
+- [ ] Link related issues/PRs
+{% endif %}
+
+## 📝 Notes
+
+{{ notes | default("Add any additional notes here") }}
+

specfact_cli/resources/templates/protocol.yaml.j2

@@ -0,0 +1,24 @@
+states:
+{% for state in states %}
+  - {{ state }}
+{% endfor %}
+
+start: {{ start }}
+
+transitions:
+{% for transition in transitions %}
+  - from_state: {{ transition.from_state }}
+    on_event: {{ transition.on_event }}
+    to_state: {{ transition.to_state }}
+    {% if transition.guard %}
+    guard: {{ transition.guard }}
+    {% endif %}
+{% endfor %}
+
+{% if guards %}
+guards:
+{% for guard_name, guard_expr in guards.items() %}
+  {{ guard_name }}: "{{ guard_expr }}"
+{% endfor %}
+{% endif %}
+

specfact_cli/resources/templates/telemetry.yaml.example

@@ -0,0 +1,35 @@
+# SpecFact CLI Telemetry Configuration
+# 
+# This is an example configuration file for SpecFact CLI telemetry.
+# 
+# To use this template:
+#   1. Copy this file to ~/.specfact/telemetry.yaml
+#   2. Customize the settings below
+#   3. Replace YOUR_BASE64_ENCODED_CREDENTIALS_HERE with your actual credentials
+#
+# For more information, see: docs/reference/telemetry.md
+
+# Enable telemetry (required)
+enabled: true
+
+# OTLP endpoint (HTTPS recommended for corporate environments)
+# Example for Grafana Cloud EU:
+# Get the exact endpoint from: Grafana Cloud Dashboard > Connections > OpenTelemetry > Send traces
+endpoint: "https://otlp-gateway-prod-eu-west-2.grafana.net/otlp/v1/traces"
+
+# Authentication headers
+# For Grafana Cloud, get credentials from: Dashboard > Connections > OpenTelemetry > Send traces
+# Format: "Basic <base64(instance-id:api-key)>"
+# The token from Grafana Cloud setup wizard can be used directly
+headers:
+  Authorization: "Basic YOUR_BASE64_ENCODED_CREDENTIALS_HERE"
+
+# Optional: Advanced configuration
+service_name: "specfact-cli"        # Custom service name (default: "specfact-cli")
+service_namespace: "cli"             # Service namespace (default: "cli") - used by Grafana Cloud
+deployment_environment: "production" # Deployment environment (default: "production") - used by Grafana Cloud
+batch_size: 512                      # Batch size (default: 512)
+batch_timeout: 5                     # Batch timeout in seconds (default: 5)
+export_timeout: 10                   # Export timeout in seconds (default: 10)
+debug: false                         # Enable console output for debugging (default: false)
+local_path: "~/.specfact/telemetry.log"  # Local log file path (default: ~/.specfact/telemetry.log)

specfact_cli/sync/__init__.py

@@ -7,6 +7,15 @@ repository changes, and SpecFact plans.
 
 from specfact_cli.sync.repository_sync import RepositorySync, RepositorySyncResult
 from specfact_cli.sync.speckit_sync import SpecKitSync, SyncResult
+from specfact_cli.sync.watcher import FileChange, SyncEventHandler, SyncWatcher
 
 
-__all__ = ["RepositorySync", "RepositorySyncResult", "SpecKitSync", "SyncResult"]
+__all__ = [
+    "FileChange",
+    "RepositorySync",
+    "RepositorySyncResult",
+    "SpecKitSync",
+    "SyncEventHandler",
+    "SyncResult",
+    "SyncWatcher",
+]