steersync 0.2.0__py3-none-any.whl

steersync/logging_utils.py

@@ -0,0 +1,60 @@
+"""Logging configuration with secret redaction and optional JSON output."""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import sys
+from datetime import UTC, datetime
+from typing import Literal
+
+_REDACT_PATTERNS: tuple[re.Pattern[str], ...] = (
+    re.compile(r"(?<=://)[^/@\s]+@"),
+    re.compile(r"gh[pousr]_[A-Za-z0-9]{36,}"),
+    re.compile(r"glpat-[A-Za-z0-9_-]{20,}"),
+    re.compile(r"(?<![A-Z0-9])(AKIA|ASIA)[0-9A-Z]{16}(?![A-Z0-9])"),
+)
+
+
+def redact(text: str) -> str:
+    """Mask credential like substrings before they reach any log sink."""
+    for pattern in _REDACT_PATTERNS:
+        text = pattern.sub("***", text)
+    return text
+
+
+class _JsonFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        payload = {
+            "time": datetime.fromtimestamp(record.created, tz=UTC).isoformat(
+                timespec="milliseconds"
+            ),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": redact(record.getMessage()),
+        }
+        if record.exc_info:
+            payload["exception"] = redact(self.formatException(record.exc_info))
+        return json.dumps(payload, ensure_ascii=False)
+
+
+class _TextFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        return redact(super().format(record))
+
+
+def configure_logging(
+    level: str = "INFO", fmt: Literal["text", "json"] = "text", *, quiet: bool = False
+) -> None:
+    """Configure the root logger for CLI use. Logs go to stderr so stdout stays machine readable."""
+    root = logging.getLogger()
+    for handler in list(root.handlers):
+        root.removeHandler(handler)
+    handler = logging.StreamHandler(sys.stderr)
+    formatter: logging.Formatter = (
+        _JsonFormatter() if fmt == "json" else _TextFormatter("%(levelname)s %(name)s: %(message)s")
+    )
+    handler.setFormatter(formatter)
+    root.addHandler(handler)
+    root.setLevel("ERROR" if quiet else level)

steersync/mcp_server.py

@@ -0,0 +1,171 @@
+"""Optional MCP stdio server exposing steersync operations as tools.
+
+Requires the ``mcp`` extra: ``pip install "steersync[mcp]"``. All tools call the
+same functions the CLI uses, so behaviour and safety checks are identical. Every
+tool takes an optional ``collections`` list (steering, specs, skills, agents,
+hooks, settings or any configured name); the default is every enabled collection.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from steersync import gitops, sync
+from steersync.config import Config, load_config
+from steersync.errors import SteersyncError
+from steersync.lint import lint_paths, merge_reports
+from steersync.paths import workspace_collection_dir
+from steersync.steering import FileSpec
+
+
+def _load(cwd: str | None) -> tuple[Config, Path | None]:
+    start = Path(cwd).expanduser() if cwd else Path.cwd()
+    bootstrap = load_config(workspace_root=None)
+    root = gitops.repo_toplevel(bootstrap, start, env=gitops.git_environment(os.environ))
+    return load_config(workspace_root=root), root
+
+
+def _plan_dict(plan: Any) -> dict[str, Any]:  # noqa: ANN401
+    if plan is None:
+        return {}
+    return {
+        "add": list(plan.add),
+        "update": list(plan.update),
+        "delete": list(plan.delete),
+        "conflict": list(plan.conflict),
+        "unchanged": len(plan.unchanged),
+        "local_only": list(plan.local_only),
+    }
+
+
+def _plans_dict(plans: dict[str, Any] | None) -> dict[str, Any]:
+    if plans is None:
+        return {}
+    return {name: _plan_dict(plan) for name, plan in plans.items()}
+
+
+def pull_steering(
+    cwd: str | None = None,
+    force: bool = False,
+    dry_run: bool = False,
+    collections: list[str] | None = None,
+) -> dict[str, Any]:
+    """Pull global and workspace collections (steering, specs, skills, ...) from central."""
+    try:
+        config, root = _load(cwd)
+        result = sync.pull(
+            config, workspace_root=root, force=force, dry_run=dry_run, collections=collections
+        )
+    except (SteersyncError, OSError) as exc:
+        return {"ok": False, "error": str(exc)}
+    scopes: dict[str, dict[str, Any]] = {}
+    for item in result.results:
+        scopes.setdefault(item.scope, {})[item.collection] = {
+            "target": str(item.target_dir),
+            "plan": _plan_dict(item.plan),
+            "written": list(item.written),
+        }
+    return {"ok": True, "commit": result.commit, "dry_run": result.dry_run, "scopes": scopes}
+
+
+def push_steering(
+    cwd: str | None = None,
+    dry_run: bool = False,
+    message: str | None = None,
+    collections: list[str] | None = None,
+) -> dict[str, Any]:
+    """Propose the workspace collections as one branch on the central repository."""
+    try:
+        config, root = _load(cwd)
+        if root is None:
+            return {"ok": False, "error": "not inside a git repository"}
+        result = sync.push(
+            config, workspace_root=root, dry_run=dry_run, message=message, collections=collections
+        )
+    except (SteersyncError, OSError) as exc:
+        return {"ok": False, "error": str(exc)}
+    return {
+        "ok": True,
+        "status": result.status,
+        "project": result.project,
+        "collections": list(result.collections),
+        "branch": result.branch,
+        "commit": result.commit,
+        "message": result.message,
+        "plan": _plan_dict(result.plan),
+    }
+
+
+def diff_steering(cwd: str | None = None, collections: list[str] | None = None) -> dict[str, Any]:
+    """Compare local collections with the central repository without changing anything."""
+    try:
+        config, root = _load(cwd)
+        result = sync.status(config, workspace_root=root, collections=collections)
+    except (SteersyncError, OSError) as exc:
+        return {"ok": False, "error": str(exc)}
+    return {
+        "ok": True,
+        "project": result.project,
+        "remote_commit": result.remote_commit,
+        "workspace": _plans_dict(result.workspace),
+        "global": _plans_dict(result.global_),
+    }
+
+
+def lint_steering(cwd: str | None = None, collections: list[str] | None = None) -> dict[str, Any]:
+    """Lint the workspace collections with each collection's profile."""
+    try:
+        config, root = _load(cwd)
+        if root is None:
+            return {"ok": False, "error": "not inside a git repository"}
+        reports = []
+        for collection in config.select_collections(collections).values():
+            target = workspace_collection_dir(collection, root)
+            if target is None:
+                continue
+            reports.append(
+                lint_paths(
+                    [target],
+                    config.lint,
+                    root,
+                    profile=collection.lint,
+                    spec=FileSpec(collection.include, collection.exclude, collection.max_depth),
+                    max_file_bytes=collection.max_file_bytes,
+                )
+            )
+        report = merge_reports(reports)
+    except (SteersyncError, OSError) as exc:
+        return {"ok": False, "error": str(exc)}
+    return {
+        "ok": report.ok,
+        "checked": report.checked,
+        "findings": [f._asdict() for f in report.findings],
+    }
+
+
+def build_server() -> Any:  # noqa: ANN401
+    """Create the MCP server. Imported lazily so the core has no MCP dependency."""
+    try:
+        from mcp.server.mcpserver import MCPServer  # noqa: PLC0415
+    except ImportError as exc:  # pragma: no cover - exercised only without the extra
+        msg = "the MCP server needs the optional dependency: pip install 'steersync[mcp]'"
+        raise SteersyncError(msg) from exc
+    server = MCPServer(
+        "steersync",
+        instructions=(
+            "Sync Kiro steering, specs, skills, agents, hooks and settings with the central "
+            "repository. Pass collections=[...] to limit a tool to some collections."
+        ),
+    )
+    server.tool(name="pull_steering")(pull_steering)
+    server.tool(name="push_steering")(push_steering)
+    server.tool(name="diff_steering")(diff_steering)
+    server.tool(name="lint_steering")(lint_steering)
+    return server
+
+
+def serve() -> None:
+    """Run the stdio MCP server until the client disconnects."""
+    build_server().run(transport="stdio")

steersync/paths.py

@@ -0,0 +1,98 @@
+"""Path resolution for Kiro directories, collection targets, locks and the clone cache."""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Mapping
+from pathlib import Path
+
+from steersync.config import CollectionConfig, Config
+from steersync.errors import UnsafePathError
+
+DEFAULT_WORKSPACE_STEERING = ".kiro/steering"
+DEFAULT_GLOBAL_STEERING = "steering"
+
+
+def kiro_home(env: Mapping[str, str]) -> Path:
+    """Return the Kiro home directory honouring ``KIRO_HOME`` like kiro-cli does."""
+    override = env.get("KIRO_HOME")
+    if override:
+        return Path(override).expanduser()
+    return Path(env.get("HOME", "~")).expanduser() / ".kiro"
+
+
+def global_collection_dir(collection: CollectionConfig, env: Mapping[str, str]) -> Path | None:
+    """Return the global target directory of a collection, or ``None`` without a global scope."""
+    if collection.global_path is None:
+        return None
+    return kiro_home(env) / collection.global_path
+
+
+def workspace_collection_dir(collection: CollectionConfig, workspace_root: Path) -> Path | None:
+    """Return the workspace target directory of a collection, or ``None`` without one."""
+    if collection.workspace_path is None:
+        return None
+    return workspace_root / collection.workspace_path
+
+
+def central_collection_dir(base: Path, collection: CollectionConfig) -> Path:
+    """Return the collection directory under a central ``global/`` or project directory."""
+    return ensure_within(base, Path(collection.central_dir or ""))
+
+
+def global_steering_dir(config: Config, env: Mapping[str, str]) -> Path:
+    """Return the global steering directory (the ``steering`` collection or its default)."""
+    steering = config.collections.get("steering")
+    relative = (
+        steering.global_path
+        if steering is not None and steering.global_path is not None
+        else DEFAULT_GLOBAL_STEERING
+    )
+    return kiro_home(env) / relative
+
+
+def workspace_steering_dir(config: Config, workspace_root: Path) -> Path:
+    """Return the workspace steering directory (the ``steering`` collection or its default)."""
+    steering = config.collections.get("steering")
+    relative = (
+        steering.workspace_path
+        if steering is not None and steering.workspace_path is not None
+        else DEFAULT_WORKSPACE_STEERING
+    )
+    return workspace_root / relative
+
+
+def global_lock_path(config: Config, env: Mapping[str, str]) -> Path:
+    return kiro_home(env) / config.paths.global_lock
+
+
+def workspace_lock_path(config: Config, workspace_root: Path) -> Path:
+    return workspace_root / config.paths.workspace_lock
+
+
+def cache_root(config: Config, env: Mapping[str, str]) -> Path:
+    raw = config.paths.cache_dir
+    if raw.startswith("~"):
+        home = env.get("HOME")
+        return Path(home) / raw[2:] if home else Path(raw).expanduser()
+    return Path(raw)
+
+
+def cache_repo_dir(config: Config, env: Mapping[str, str], remote_url: str) -> Path:
+    """Return a stable cache directory for a remote URL."""
+    digest = hashlib.sha256(remote_url.encode("utf-8")).hexdigest()[:16]
+    return cache_root(config, env) / "repos" / digest
+
+
+def ensure_within(base: Path, candidate: Path) -> Path:
+    """Resolve ``candidate`` and ensure it stays inside ``base``."""
+    base_resolved = base.resolve()
+    target = (
+        (base_resolved / candidate).resolve()
+        if not candidate.is_absolute()
+        else candidate.resolve()
+    )
+    if target != base_resolved and base_resolved not in target.parents:
+        msg = f"path {candidate} escapes {base}"
+        raise UnsafePathError(msg)
+    return target

steersync/resources/default_config.yaml

@@ -0,0 +1,154 @@
+# Default steersync configuration. User configuration files are deep merged over
+# these values. Environment variables override individual settings; see README.
+remote:
+  # URL of the central steering repository. SSH or HTTPS. Authentication is
+  # handled by the git binary (ssh-agent or credential helper), never by steersync.
+  url: ""
+  default_branch: main
+  # Directory in the central repository holding steering applied to every workspace.
+  global_dir: global
+  # Directory in the central repository holding per project steering, keyed by project slug.
+  projects_dir: projects
+  # Optional allow list of remote hosts. Empty means any host is accepted.
+  allowed_hosts: []
+  # Allow file:// and absolute local paths. Only for tests and offline evaluation.
+  allow_local: false
+  # Git push options sent with each proposal branch. Placeholders: {default_branch},
+  # {project}, {user}, {hash}. GitLab turns these into a merge request; other
+  # servers ignore them silently.
+  push_options:
+    - merge_request.create
+    - merge_request.target={default_branch}
+    - merge_request.remove_source_branch
+    - "merge_request.title=steering: update {project} from {user}"
+
+git:
+  binary: git
+  # Per invocation timeout. Network operations (clone, fetch, ls-remote, push)
+  # are retried on transient failures with exponential backoff and jitter.
+  timeout_seconds: 120
+  clone_depth: 1
+  retries: 2
+  retry_backoff_seconds: 2.0
+  retry_max_backoff_seconds: 30.0
+
+branch:
+  # Placeholders: {project}, {user}, {hash}
+  template: "steering/{project}/{user}-{hash}"
+  hash_length: 8
+
+paths:
+  workspace_lock: .kiro/steersync.lock.json
+  # Resolved against KIRO_HOME when set, else ~/.kiro
+  global_lock: steersync.lock.json
+  cache_dir: ~/.cache/steersync
+
+# Collections are the kinds of Kiro content that are synced. Each one maps a
+# workspace directory (relative to the repository root) and, optionally, a global
+# directory (relative to KIRO_HOME, default ~/.kiro) onto a directory in the
+# central repository: global/<central_dir>/ and projects/<slug>/<central_dir>/.
+#
+# include and exclude are glob patterns relative to the collection directory
+# (** spans directories). lint selects the validation profile: steering,
+# markdown, skill, agent, hooks, json or generic. Set enabled: false to switch a
+# collection off, or add a new key to sync something else. Hidden files and
+# directories are never synced.
+collections:
+  steering:
+    description: Kiro steering documents
+    workspace_path: .kiro/steering
+    global_path: steering
+    central_dir: steering
+    include: ["**/*.md"]
+    lint: steering
+  specs:
+    description: Spec driven development plans (requirements, design, tasks)
+    workspace_path: .kiro/specs
+    global_path: null
+    central_dir: specs
+    include: ["**/*.md"]
+    lint: markdown
+  skills:
+    description: Agent Skills (SKILL.md with scripts, references and assets)
+    workspace_path: .kiro/skills
+    global_path: skills
+    central_dir: skills
+    include: ["**/*"]
+    exclude: ["**/__pycache__/**", "**/node_modules/**"]
+    lint: skill
+    max_file_bytes: 1048576
+  agents:
+    description: Custom agent definitions and their prompt files
+    workspace_path: .kiro/agents
+    global_path: agents
+    central_dir: agents
+    include: ["**/*.json", "**/*.md"]
+    lint: agent
+  hooks:
+    description: Standalone Kiro hooks (V3 and IDE 1.0)
+    workspace_path: .kiro/hooks
+    global_path: hooks
+    central_dir: hooks
+    include: ["**/*.json"]
+    lint: hooks
+  settings:
+    description: Workspace settings such as the language server configuration
+    workspace_path: .kiro/settings
+    global_path: null
+    central_dir: settings
+    include: ["lsp.json", "mcp.json"]
+    lint: json
+
+sync:
+  # Delete locally managed files that disappeared from the central repository.
+  prune: true
+  # Fail a pull when the remote content has lint errors.
+  strict_pull: false
+  # Wait this long for another steersync process using the same cache clone.
+  lock_timeout_seconds: 120
+  # Safety limits for content read from the central repository.
+  max_files: 1000
+  max_total_bytes: 10485760
+
+lint:
+  max_file_bytes: 65536
+  require_h1: true
+  allowed_extra_keys:
+    - x-steersync
+  file_reference_check: true
+  pymarkdown:
+    enabled: true
+    severity: warning
+    disabled_rules:
+      - MD013   # line length is not meaningful for prose steering
+      - MD041   # first line heading is handled by require_h1 with front matter awareness
+  forbidden_patterns:
+    - id: aws-access-key
+      pattern: "(?<![A-Z0-9])(AKIA|ASIA)[0-9A-Z]{16}(?![A-Z0-9])"
+      message: AWS access key identifier
+    - id: private-key
+      pattern: "-----BEGIN (RSA |EC |DSA |OPENSSH |PGP )?PRIVATE KEY"
+      message: Private key material
+    - id: github-token
+      pattern: "gh[pousr]_[A-Za-z0-9]{36,}"
+      message: GitHub token
+    - id: gitlab-token
+      pattern: "glpat-[A-Za-z0-9_-]{20,}"
+      message: GitLab personal access token
+    - id: slack-token
+      pattern: "xox[abpr]-[0-9A-Za-z-]{10,}"
+      message: Slack token
+    - id: generic-secret
+      pattern: "(?i)(api[_-]?key|secret|password|token)\\s*[:=]\\s*['\"][A-Za-z0-9/+_=-]{16,}['\"]"
+      message: Possible hard coded credential
+
+hook:
+  # When true the pre-push hook aborts the project push if steering sync fails.
+  strict: false
+  # Per git call timeout while running from a hook, so a slow server never
+  # stalls the developer's push for long.
+  timeout_seconds: 60
+
+logging:
+  level: INFO
+  format: text