steersync 0.3.0__tar.gz → 0.4.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {steersync-0.3.0 → steersync-0.4.0}/CHANGELOG.md +50 -0
- steersync-0.3.0/README.md → steersync-0.4.0/PKG-INFO +90 -22
- steersync-0.3.0/PKG-INFO → steersync-0.4.0/README.md +58 -53
- {steersync-0.3.0 → steersync-0.4.0}/pyproject.toml +20 -14
- {steersync-0.3.0 → steersync-0.4.0}/scripts/prepare_release.py +0 -2
- {steersync-0.3.0 → steersync-0.4.0}/src/steersync/__init__.py +1 -1
- {steersync-0.3.0 → steersync-0.4.0}/src/steersync/cli.py +129 -7
- {steersync-0.3.0 → steersync-0.4.0}/src/steersync/config.py +39 -8
- {steersync-0.3.0 → steersync-0.4.0}/src/steersync/gitlab.py +0 -2
- {steersync-0.3.0 → steersync-0.4.0}/src/steersync/gitops.py +0 -2
- {steersync-0.3.0 → steersync-0.4.0}/src/steersync/hooks.py +29 -7
- steersync-0.4.0/src/steersync/kiro_rules.py +819 -0
- steersync-0.4.0/src/steersync/kiro_version.py +269 -0
- {steersync-0.3.0 → steersync-0.4.0}/src/steersync/lint.py +80 -86
- {steersync-0.3.0 → steersync-0.4.0}/src/steersync/locking.py +2 -4
- {steersync-0.3.0 → steersync-0.4.0}/src/steersync/logging_utils.py +0 -2
- {steersync-0.3.0 → steersync-0.4.0}/src/steersync/mcp_server.py +107 -24
- steersync-0.4.0/src/steersync/migrate.py +175 -0
- {steersync-0.3.0 → steersync-0.4.0}/src/steersync/paths.py +0 -2
- {steersync-0.3.0 → steersync-0.4.0}/src/steersync/practices.py +0 -11
- {steersync-0.3.0 → steersync-0.4.0}/src/steersync/resources/default_config.yaml +61 -9
- {steersync-0.3.0 → steersync-0.4.0}/src/steersync/steering.py +32 -7
- {steersync-0.3.0 → steersync-0.4.0}/src/steersync/sync.py +0 -2
- {steersync-0.3.0 → steersync-0.4.0}/tests/conftest.py +7 -2
- {steersync-0.3.0 → steersync-0.4.0}/tests/test_automation.py +0 -2
- {steersync-0.3.0 → steersync-0.4.0}/tests/test_cli.py +3 -2
- {steersync-0.3.0 → steersync-0.4.0}/tests/test_collections.py +31 -5
- {steersync-0.3.0 → steersync-0.4.0}/tests/test_config.py +5 -2
- {steersync-0.3.0 → steersync-0.4.0}/tests/test_gitlab.py +0 -2
- {steersync-0.3.0 → steersync-0.4.0}/tests/test_gitops.py +0 -2
- {steersync-0.3.0 → steersync-0.4.0}/tests/test_hardening.py +0 -2
- {steersync-0.3.0 → steersync-0.4.0}/tests/test_hooks.py +27 -4
- steersync-0.4.0/tests/test_kiro_collections.py +156 -0
- steersync-0.4.0/tests/test_kiro_rules.py +341 -0
- steersync-0.4.0/tests/test_kiro_version.py +187 -0
- {steersync-0.3.0 → steersync-0.4.0}/tests/test_lint.py +3 -3
- {steersync-0.3.0 → steersync-0.4.0}/tests/test_mcp_server.py +17 -2
- steersync-0.4.0/tests/test_migrate.py +111 -0
- {steersync-0.3.0 → steersync-0.4.0}/tests/test_practices.py +1 -4
- {steersync-0.3.0 → steersync-0.4.0}/tests/test_prepare_release.py +0 -2
- {steersync-0.3.0 → steersync-0.4.0}/tests/test_steering.py +0 -2
- {steersync-0.3.0 → steersync-0.4.0}/tests/test_sync.py +5 -2
- {steersync-0.3.0 → steersync-0.4.0}/.gitignore +0 -0
- {steersync-0.3.0 → steersync-0.4.0}/LICENSE +0 -0
- {steersync-0.3.0 → steersync-0.4.0}/src/steersync/__main__.py +0 -0
- {steersync-0.3.0 → steersync-0.4.0}/src/steersync/errors.py +0 -0
- {steersync-0.3.0 → steersync-0.4.0}/steersync.example.yaml +0 -0
- {steersync-0.3.0 → steersync-0.4.0}/tests/__init__.py +0 -0
|
@@ -5,6 +5,56 @@ Keep a Changelog and the project uses semantic versioning.
|
|
|
5
5
|
|
|
6
6
|
## [Unreleased]
|
|
7
7
|
|
|
8
|
+
## [0.4.0] - 2026-11-22
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- Collections for the rest of the committable Kiro configuration (Kiro IDE 1.5, Kiro CLI 3.5):
|
|
13
|
+
`workflows` (`.kiro/workflows/*.workflow.{json,yaml,yml}` and `~/.kiro/workflows`),
|
|
14
|
+
`sandbox` (`.kiro/settings/sandbox.json`), `kiroignore` (`.kiroignore` at any depth and
|
|
15
|
+
`~/.kiro/settings/kiroignore`) and the opt in `cli-settings` (`.kiro/settings/cli.json`).
|
|
16
|
+
`agents-md` now syncs nested `AGENTS.md` files, and `specs` syncs every file in a spec
|
|
17
|
+
directory (`bugfix.md`, metadata), not only markdown.
|
|
18
|
+
- Schema rules (`steersync.kiro_rules`): hooks need `version: "v1"` and a matching
|
|
19
|
+
`action.command` or `action.prompt`; integer timeouts; `confirm` only on `Stop` command
|
|
20
|
+
hooks; the `SessionEnd`, `PermissionRequest`, `PreCompact` and `PostCompact` triggers, with
|
|
21
|
+
CLI 2.x camelCase names flagged. Agents: V2 format (`toolsSettings` or `allowedTools`
|
|
22
|
+
without `permissions`) is an error because Kiro rewrites such files on load, plus checks
|
|
23
|
+
for `permissions.rules`, 2.x tool names, `use_aws`, `toolAliases`, `keyboardShortcut`,
|
|
24
|
+
resource schemes, home directory paths and inline V3 hooks, for JSON and Markdown agents.
|
|
25
|
+
`mcp.json`: literal secrets in `env`, `headers` and `oauth.clientSecret`, `oauth.mode`,
|
|
26
|
+
`clientMetadataUrl`, timeouts. `sandbox.json`, workspace `cli.json`, workflow recipes
|
|
27
|
+
(node types, unique ids, `repeat` limits, join policies, depth and size) and
|
|
28
|
+
`.kiroignore` syntax.
|
|
29
|
+
- Kiro CLI V3 harness detection: `steersync v3-status`, a harness section in `doctor`, the
|
|
30
|
+
`kiro_v3_status` MCP tool and a once a day reminder from the session hook. Uses only
|
|
31
|
+
`kiro-cli --version` and `kiro-cli settings`, never a chat session.
|
|
32
|
+
- `steersync migrate-hooks` converts `*.kiro.hook` files and CLI 2.x inline agent hooks into
|
|
33
|
+
standalone `.kiro/hooks/*.json` files (dry run by default).
|
|
34
|
+
- The `steersync-mcp` entry point, MCP tool titles and read only, destructive and idempotent
|
|
35
|
+
annotations, server version and title, `confirm` for a forced pull, and logs on stderr.
|
|
36
|
+
|
|
37
|
+
### Changed
|
|
38
|
+
|
|
39
|
+
- The rendered `mcp.json` entry runs `uvx --from "steersync[mcp]==<version>" steersync mcp`
|
|
40
|
+
(the previous `uvx steersync mcp` lacked the `mcp` extra) and auto approves the read only
|
|
41
|
+
tools.
|
|
42
|
+
- Collections may share a directory when each selects its files by literal name and the
|
|
43
|
+
names do not overlap. Hidden files are synced when a pattern names them literally, and
|
|
44
|
+
excluded trees such as `node_modules` are no longer walked.
|
|
45
|
+
- Dependency floors: click 8.5.1, pydantic 2.14.4, PyYAML 6.0.4, pymarkdownlnt 0.9.42,
|
|
46
|
+
hatchling 1.33, pytest 9.2, ruff 0.17.6, bandit 1.9, pip-audit 2.10. pytest uses its
|
|
47
|
+
native TOML configuration, coverage must stay at 90 per cent, CI also tests Python 3.15
|
|
48
|
+
and runs ty as an advisory check, and `from __future__ import annotations` is gone
|
|
49
|
+
(Python 3.14 defers annotations).
|
|
50
|
+
|
|
51
|
+
### Fixed
|
|
52
|
+
|
|
53
|
+
- The Kiro session hook command `steersync pull --quiet --best-effort` failed with "No such
|
|
54
|
+
option: --quiet"; `pull` now accepts `-q/--quiet`.
|
|
55
|
+
- `steersync lint FILE` crashed for a file outside the repository, and
|
|
56
|
+
`steersync lint --profile P DIR` used the steering file patterns for every profile.
|
|
57
|
+
|
|
8
58
|
## [0.3.0] - 2026-10-13
|
|
9
59
|
|
|
10
60
|
### Added
|
|
@@ -1,7 +1,42 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: steersync
|
|
3
|
+
Version: 0.4.0
|
|
4
|
+
Summary: Sync Kiro configuration (steering, specs, skills, agents, hooks, workflows, settings) with a central git repository.
|
|
5
|
+
Project-URL: Homepage, https://github.com/SCGIS-Wales/steersync
|
|
6
|
+
Project-URL: Repository, https://github.com/SCGIS-Wales/steersync
|
|
7
|
+
Project-URL: Issues, https://github.com/SCGIS-Wales/steersync/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/SCGIS-Wales/steersync/blob/main/CHANGELOG.md
|
|
9
|
+
Author-email: Dejan Gregor <dejan.gregor@gmail.com>
|
|
10
|
+
License-Expression: Apache-2.0
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: agents,developer-experience,git,hooks,kiro,kiro-cli,mcp,pre-push,steering,workflows
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Environment :: Console
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
21
|
+
Classifier: Topic :: Software Development :: Version Control :: Git
|
|
22
|
+
Classifier: Typing :: Typed
|
|
23
|
+
Requires-Python: >=3.14
|
|
24
|
+
Requires-Dist: click<9,>=8.5.1
|
|
25
|
+
Requires-Dist: pydantic<3,>=2.14.4
|
|
26
|
+
Requires-Dist: pymarkdownlnt<1,>=0.9.42
|
|
27
|
+
Requires-Dist: python-frontmatter<2,>=1.3
|
|
28
|
+
Requires-Dist: pyyaml<7,>=6.0.4
|
|
29
|
+
Provides-Extra: mcp
|
|
30
|
+
Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
|
|
31
|
+
Description-Content-Type: text/markdown
|
|
32
|
+
|
|
1
33
|
# steersync
|
|
2
34
|
|
|
3
|
-
Sync the whole [Kiro](https://kiro.dev) `.kiro/` configuration
|
|
4
|
-
agents, hooks
|
|
35
|
+
Sync the whole [Kiro](https://kiro.dev) `.kiro/` configuration (steering, specs, skills,
|
|
36
|
+
agents, hooks, settings, the sandbox policy, workflow recipes, prompts, `AGENTS.md` and
|
|
37
|
+
`.kiroignore` files) between developer machines and a central git repository. It targets Kiro
|
|
38
|
+
IDE 1.5 and Kiro CLI 3.5 with the V3 agent harness, and reminds you when a machine is still
|
|
39
|
+
on V2. A plain
|
|
5
40
|
Python CLI runs from a git pre-push hook and shells out to the `git` binary, so your existing
|
|
6
41
|
SSH agent or credential helper does the authentication. An MCP server and Kiro session hooks
|
|
7
42
|
are optional layers on top of the same core.
|
|
@@ -24,23 +59,33 @@ layout; each one is configurable and new ones are added with a single YAML block
|
|
|
24
59
|
| Collection | Workspace | Global (`~/.kiro`) | Central directory | Files | Lint profile |
|
|
25
60
|
|---|---|---|---|---|---|
|
|
26
61
|
| `steering` | `.kiro/steering` | `steering` | `steering/` | `**/*.md` | `steering`: Kiro front matter, references, secrets, markdown |
|
|
27
|
-
| `specs` | `.kiro/specs` | none | `specs/` |
|
|
62
|
+
| `specs` | `.kiro/specs` | none | `specs/` | every file in each spec (`requirements.md` or `bugfix.md`, `design.md`, `tasks.md`, metadata) | `markdown`: secrets and markdown style |
|
|
28
63
|
| `skills` | `.kiro/skills` | `skills` | `skills/` | everything (`SKILL.md`, `scripts/`, `references/`, `assets/`) | `skill`: `SKILL.md` needs `name` and `description`, secrets in scripts |
|
|
29
|
-
| `agents` | `.kiro/agents` | `agents` | `agents/` | `**/*.json`, `**/*.md` | `agent`:
|
|
30
|
-
| `hooks` | `.kiro/hooks` | `hooks` | `hooks/` | `**/*.json` | `hooks`: `version`,
|
|
31
|
-
| `settings` | `.kiro/settings` | none | `settings/` | `lsp.json`, `mcp.json` | `settings`:
|
|
64
|
+
| `agents` | `.kiro/agents` | `agents` | `agents/` | `**/*.json`, `**/*.md` (not the `*.json.bak` upgrade backups) | `agent`: V3 universal format, `permissions.rules`, tool names, resources, inline hooks |
|
|
65
|
+
| `hooks` | `.kiro/hooks` | `hooks` | `hooks/` | `**/*.json`, legacy `**/*.kiro.hook` | `hooks`: `version: v1`, triggers, actions, timeouts, `confirm` |
|
|
66
|
+
| `settings` | `.kiro/settings` | none | `settings/` | `lsp.json`, `mcp.json` | `settings`: shapes, literal secrets, OAuth, machine paths |
|
|
67
|
+
| `sandbox` | `.kiro/settings` | none | `sandbox/` | `sandbox.json` | `settings`: `enabled`, `networkAccess` |
|
|
68
|
+
| `cli-settings` (off by default) | `.kiro/settings` | none | `cli-settings/` | `cli.json` | `settings`: rejects global only keys such as `chat.agentEngine` |
|
|
69
|
+
| `workflows` | `.kiro/workflows` | `workflows` | `workflows/` | `**/*.workflow.json`, `.yaml`, `.yml` | `workflow`: the recipe schema of Kiro CLI 3.5 |
|
|
32
70
|
| `prompts` | `.kiro/prompts` | `prompts` | `prompts/` | `**/*.md` | `prompt`: markdown plus the 50 character name limit |
|
|
33
|
-
| `agents-md` |
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
71
|
+
| `agents-md` | the repository | none | `agents-md/` | `**/AGENTS.md` (root and nested) | `markdown` (kept in the project repository too) |
|
|
72
|
+
| `kiroignore` | the repository | `settings` (`kiroignore`) | `kiroignore/` | `**/.kiroignore` | `kiroignore`: gitignore syntax, advice on `.env*` and `*.pem` |
|
|
73
|
+
|
|
74
|
+
Execute bits on skill scripts survive the round trip. Hidden directories are never synced,
|
|
75
|
+
and a hidden file only when a pattern names it (`**/.kiroignore`). Files a collection's
|
|
76
|
+
patterns do not select are never touched on either side, which is why `settings`, `sandbox`
|
|
77
|
+
and `cli-settings` can share `.kiro/settings`. The repository wide collections skip
|
|
78
|
+
`node_modules`, virtual environments, `dist`, `build` and `target` without walking them. Limit any
|
|
37
79
|
command to some collections with `--collection NAME` (repeatable), list them with
|
|
38
80
|
`steersync config collections`, and see [docs/central-layout.md](docs/central-layout.md) for
|
|
39
81
|
a worked example of a full `.kiro/` tree in the central repository.
|
|
40
82
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
83
|
+
Never synced, by design: workspace permissions (`~/.kiro/workspace-roots/<hash>/permissions.yaml`,
|
|
84
|
+
kept per user so that a cloned repository cannot inject permission rules) and
|
|
85
|
+
`~/.kiro/settings/permissions.yaml`, `~/.kiro/powers/` (installed from a registry),
|
|
86
|
+
`~/.kiro/memories/`, `~/.kiro/sessions/`, `~/.kiro/crew/`, `~/.kiro/settings/cli.json`,
|
|
87
|
+
`managed-settings.json` and knowledge base indexes (the declarations in agent `resources`
|
|
88
|
+
are synced with the agent). Every path above comes from
|
|
44
89
|
the Kiro configuration scopes documentation; a new kind of content is one YAML block.
|
|
45
90
|
|
|
46
91
|
## Install
|
|
@@ -50,8 +95,11 @@ Requires Python 3.14 or newer and git 2.18 or newer. Every
|
|
|
50
95
|
sdist and a `SHA256SUMS` file, with signed build provenance.
|
|
51
96
|
|
|
52
97
|
```bash
|
|
53
|
-
VERSION=0.
|
|
98
|
+
VERSION=0.4.0
|
|
54
99
|
uv tool install "https://github.com/SCGIS-Wales/steersync/releases/download/v${VERSION}/steersync-${VERSION}-py3-none-any.whl"
|
|
100
|
+
# or run it without installing
|
|
101
|
+
uvx steersync --help
|
|
102
|
+
uvx --from "steersync[mcp]" steersync-mcp
|
|
55
103
|
# with the MCP server
|
|
56
104
|
uv tool install "steersync[mcp] @ https://github.com/SCGIS-Wales/steersync/releases/download/v${VERSION}/steersync-${VERSION}-py3-none-any.whl"
|
|
57
105
|
# verify where the wheel came from
|
|
@@ -151,10 +199,12 @@ subdirectory; `pull` and `status` print a warning pointing at them until that is
|
|
|
151
199
|
| `steersync init [--write-config] [--hook] [--no-exclude] [--no-kiro] [--mcp-command PATH]` | Prepare a repository: excludes, git hook, Kiro session hook and MCP server entry. |
|
|
152
200
|
| `steersync install-hook [--force]` | Install or update the chaining pre-push hook. |
|
|
153
201
|
| `steersync kiro-hook [--engine v2\|v3] [--write]` | Render a Kiro hook that runs `steersync pull --quiet` at session start. |
|
|
154
|
-
| `steersync
|
|
155
|
-
| `steersync
|
|
202
|
+
| `steersync migrate-hooks [--write]` | Convert `*.kiro.hook` files and CLI 2.x inline agent hooks into `.kiro/hooks/*.json`. Dry run by default; never overwrites or deletes. |
|
|
203
|
+
| `steersync v3-status [--json] [--strict]` | Report the kiro-cli version, `chat.agentEngine` and agents still in the V2 format. `--strict` exits 10 when a reminder applies. |
|
|
204
|
+
| `steersync mcp-config [--command uvx] [--remote URL]` | Render an `mcp.json` fragment. |
|
|
205
|
+
| `steersync mcp` (or `steersync-mcp`) | Run the MCP stdio server. |
|
|
156
206
|
| `steersync config show\|validate\|default\|collections` | Inspect configuration and the resolved collection directories. |
|
|
157
|
-
| `steersync doctor` | Report git version, resolved paths, remote and
|
|
207
|
+
| `steersync doctor` | Report git version, resolved paths, remote, project slug and the Kiro CLI harness. |
|
|
158
208
|
|
|
159
209
|
Global options: `--config PATH`, `--log-level`, `--log-format text|json`, `--quiet`.
|
|
160
210
|
|
|
@@ -259,7 +309,7 @@ Teams that already use [pre-commit](https://pre-commit.com) can use the publishe
|
|
|
259
309
|
default_install_hook_types: [pre-commit, pre-push]
|
|
260
310
|
repos:
|
|
261
311
|
- repo: https://github.com/SCGIS-Wales/steersync
|
|
262
|
-
rev: v0.
|
|
312
|
+
rev: v0.4.0
|
|
263
313
|
hooks:
|
|
264
314
|
- id: steersync-push
|
|
265
315
|
- id: steersync-lint
|
|
@@ -307,9 +357,12 @@ The merge request is opened in two ways:
|
|
|
307
357
|
## Validation
|
|
308
358
|
|
|
309
359
|
Each collection runs one lint profile: `steering`, `agent`, `hooks`, `skill`, `settings`,
|
|
310
|
-
`prompt`, `markdown`, `json` or `generic`. **Errors** are things
|
|
311
|
-
matter after a blank line, an unknown inclusion
|
|
312
|
-
`name` and `description
|
|
360
|
+
`prompt`, `workflow`, `kiroignore`, `markdown`, `json` or `generic`. **Errors** are things
|
|
361
|
+
Kiro cannot read or would rewrite (front matter after a blank line, an unknown inclusion
|
|
362
|
+
mode, invalid JSON, a `SKILL.md` without `name` and `description`, a hook without
|
|
363
|
+
`version: "v1"`, a workflow `repeat` without `maxIterations`, an unknown sandbox
|
|
364
|
+
`networkAccess`, a V2 format agent) or secrets, including literal tokens in `mcp.json`
|
|
365
|
+
`env`, `headers` and `oauth.clientSecret`; they stop a push. **Warnings** are best practices from
|
|
313
366
|
the Kiro documentation, reported objectively and never blocking: a steering file with a
|
|
314
367
|
numeric prefix, an `auto` description that is not written as a trigger, a `globs` key where
|
|
315
368
|
Kiro reads `fileMatchPattern`, an agent with `tools: ["*"]` or a `file://.kiro/steering/**`
|
|
@@ -329,8 +382,22 @@ and `lint.practices: false` turns the warnings off.
|
|
|
329
382
|
fire only in headless runs or with a custom agent active, so treat them as a convenience and
|
|
330
383
|
keep the git hook as the dependable trigger.
|
|
331
384
|
|
|
385
|
+
**Kiro CLI V3.** Kiro CLI 3.0.0 made V3 the default agent harness; V2 still runs but gets no
|
|
386
|
+
new features. `steersync doctor`, `steersync v3-status`, the `kiro_v3_status` MCP tool and
|
|
387
|
+
the session hook (at most once a day) check `kiro-cli --version`, `chat.agentEngine` and your
|
|
388
|
+
agent files. When a reminder applies, run `kiro-cli settings chat.agentEngine v3`, start
|
|
389
|
+
`kiro-cli` and run `/upgrade-agent`; for a shared agent directory run
|
|
390
|
+
`kiro-cli agent upgrade <dir>`. See <https://kiro.dev/docs/cli/v3/>. The probes never start a
|
|
391
|
+
chat, so they use no Kiro credits, and a reminder never fails a sync. Set
|
|
392
|
+
`STEERSYNC_NO_V3_REMINDER=1` to silence the session hook reminder.
|
|
393
|
+
|
|
332
394
|
**MCP server.** `steersync init` registers the server in `.kiro/settings/mcp.json`
|
|
333
|
-
(`steersync mcp-config` prints the fragment).
|
|
395
|
+
(`steersync mcp-config` prints the fragment). It runs through
|
|
396
|
+
`uvx --from "steersync[mcp]==<version>" steersync mcp`, so nothing needs installing, and it
|
|
397
|
+
auto approves only the read only tools. The server is built on the MCP Python SDK v2
|
|
398
|
+
(`MCPServer`, specification 2026-07-28): tools return structured JSON and carry titles and
|
|
399
|
+
read only, destructive and idempotent hints. A forced pull needs `confirm: true` because it
|
|
400
|
+
overwrites local edits. The server tells the agent which tool answers
|
|
334
401
|
which request, so plain sentences work:
|
|
335
402
|
|
|
336
403
|
| Say | Tool |
|
|
@@ -341,6 +408,7 @@ which request, so plain sentences work:
|
|
|
341
408
|
| "what changed", "status", "any open proposals for this repo" | `diff_kiro_config` |
|
|
342
409
|
| "validate / lint / check the kiro config, agents, hooks, skills" | `validate_kiro_config` |
|
|
343
410
|
| "what is synced and where" | `list_kiro_collections` |
|
|
411
|
+
| "am I on Kiro V3", "do my agents need upgrading" | `kiro_v3_status` |
|
|
344
412
|
|
|
345
413
|
Every tool accepts a `collections` list. Kiro does not pass the shell's `PATH`,
|
|
346
414
|
`SSH_AUTH_SOCK`, proxy variables or `GITLAB_TOKEN` to MCP servers, so the rendered entry
|
|
@@ -1,38 +1,10 @@
|
|
|
1
|
-
Metadata-Version: 2.5
|
|
2
|
-
Name: steersync
|
|
3
|
-
Version: 0.3.0
|
|
4
|
-
Summary: Sync Kiro steering documents between developer machines and a central git repository.
|
|
5
|
-
Project-URL: Homepage, https://github.com/SCGIS-Wales/steersync
|
|
6
|
-
Project-URL: Repository, https://github.com/SCGIS-Wales/steersync
|
|
7
|
-
Project-URL: Issues, https://github.com/SCGIS-Wales/steersync/issues
|
|
8
|
-
Project-URL: Changelog, https://github.com/SCGIS-Wales/steersync/blob/main/CHANGELOG.md
|
|
9
|
-
Author-email: Dejan Gregor <dejan.gregor@gmail.com>
|
|
10
|
-
License-Expression: Apache-2.0
|
|
11
|
-
License-File: LICENSE
|
|
12
|
-
Keywords: developer-experience,git,kiro,mcp,pre-push,steering
|
|
13
|
-
Classifier: Development Status :: 4 - Beta
|
|
14
|
-
Classifier: Environment :: Console
|
|
15
|
-
Classifier: Intended Audience :: Developers
|
|
16
|
-
Classifier: Operating System :: OS Independent
|
|
17
|
-
Classifier: Programming Language :: Python :: 3
|
|
18
|
-
Classifier: Programming Language :: Python :: 3 :: Only
|
|
19
|
-
Classifier: Programming Language :: Python :: 3.14
|
|
20
|
-
Classifier: Topic :: Software Development :: Version Control :: Git
|
|
21
|
-
Classifier: Typing :: Typed
|
|
22
|
-
Requires-Python: >=3.14
|
|
23
|
-
Requires-Dist: click<9,>=8.5
|
|
24
|
-
Requires-Dist: pydantic<3,>=2.14
|
|
25
|
-
Requires-Dist: pymarkdownlnt<1,>=0.9.40
|
|
26
|
-
Requires-Dist: python-frontmatter<2,>=1.3
|
|
27
|
-
Requires-Dist: pyyaml<7,>=6.0.3
|
|
28
|
-
Provides-Extra: mcp
|
|
29
|
-
Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
|
|
30
|
-
Description-Content-Type: text/markdown
|
|
31
|
-
|
|
32
1
|
# steersync
|
|
33
2
|
|
|
34
|
-
Sync the whole [Kiro](https://kiro.dev) `.kiro/` configuration
|
|
35
|
-
agents, hooks
|
|
3
|
+
Sync the whole [Kiro](https://kiro.dev) `.kiro/` configuration (steering, specs, skills,
|
|
4
|
+
agents, hooks, settings, the sandbox policy, workflow recipes, prompts, `AGENTS.md` and
|
|
5
|
+
`.kiroignore` files) between developer machines and a central git repository. It targets Kiro
|
|
6
|
+
IDE 1.5 and Kiro CLI 3.5 with the V3 agent harness, and reminds you when a machine is still
|
|
7
|
+
on V2. A plain
|
|
36
8
|
Python CLI runs from a git pre-push hook and shells out to the `git` binary, so your existing
|
|
37
9
|
SSH agent or credential helper does the authentication. An MCP server and Kiro session hooks
|
|
38
10
|
are optional layers on top of the same core.
|
|
@@ -55,23 +27,33 @@ layout; each one is configurable and new ones are added with a single YAML block
|
|
|
55
27
|
| Collection | Workspace | Global (`~/.kiro`) | Central directory | Files | Lint profile |
|
|
56
28
|
|---|---|---|---|---|---|
|
|
57
29
|
| `steering` | `.kiro/steering` | `steering` | `steering/` | `**/*.md` | `steering`: Kiro front matter, references, secrets, markdown |
|
|
58
|
-
| `specs` | `.kiro/specs` | none | `specs/` |
|
|
30
|
+
| `specs` | `.kiro/specs` | none | `specs/` | every file in each spec (`requirements.md` or `bugfix.md`, `design.md`, `tasks.md`, metadata) | `markdown`: secrets and markdown style |
|
|
59
31
|
| `skills` | `.kiro/skills` | `skills` | `skills/` | everything (`SKILL.md`, `scripts/`, `references/`, `assets/`) | `skill`: `SKILL.md` needs `name` and `description`, secrets in scripts |
|
|
60
|
-
| `agents` | `.kiro/agents` | `agents` | `agents/` | `**/*.json`, `**/*.md` | `agent`:
|
|
61
|
-
| `hooks` | `.kiro/hooks` | `hooks` | `hooks/` | `**/*.json` | `hooks`: `version`,
|
|
62
|
-
| `settings` | `.kiro/settings` | none | `settings/` | `lsp.json`, `mcp.json` | `settings`:
|
|
32
|
+
| `agents` | `.kiro/agents` | `agents` | `agents/` | `**/*.json`, `**/*.md` (not the `*.json.bak` upgrade backups) | `agent`: V3 universal format, `permissions.rules`, tool names, resources, inline hooks |
|
|
33
|
+
| `hooks` | `.kiro/hooks` | `hooks` | `hooks/` | `**/*.json`, legacy `**/*.kiro.hook` | `hooks`: `version: v1`, triggers, actions, timeouts, `confirm` |
|
|
34
|
+
| `settings` | `.kiro/settings` | none | `settings/` | `lsp.json`, `mcp.json` | `settings`: shapes, literal secrets, OAuth, machine paths |
|
|
35
|
+
| `sandbox` | `.kiro/settings` | none | `sandbox/` | `sandbox.json` | `settings`: `enabled`, `networkAccess` |
|
|
36
|
+
| `cli-settings` (off by default) | `.kiro/settings` | none | `cli-settings/` | `cli.json` | `settings`: rejects global only keys such as `chat.agentEngine` |
|
|
37
|
+
| `workflows` | `.kiro/workflows` | `workflows` | `workflows/` | `**/*.workflow.json`, `.yaml`, `.yml` | `workflow`: the recipe schema of Kiro CLI 3.5 |
|
|
63
38
|
| `prompts` | `.kiro/prompts` | `prompts` | `prompts/` | `**/*.md` | `prompt`: markdown plus the 50 character name limit |
|
|
64
|
-
| `agents-md` |
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
39
|
+
| `agents-md` | the repository | none | `agents-md/` | `**/AGENTS.md` (root and nested) | `markdown` (kept in the project repository too) |
|
|
40
|
+
| `kiroignore` | the repository | `settings` (`kiroignore`) | `kiroignore/` | `**/.kiroignore` | `kiroignore`: gitignore syntax, advice on `.env*` and `*.pem` |
|
|
41
|
+
|
|
42
|
+
Execute bits on skill scripts survive the round trip. Hidden directories are never synced,
|
|
43
|
+
and a hidden file only when a pattern names it (`**/.kiroignore`). Files a collection's
|
|
44
|
+
patterns do not select are never touched on either side, which is why `settings`, `sandbox`
|
|
45
|
+
and `cli-settings` can share `.kiro/settings`. The repository wide collections skip
|
|
46
|
+
`node_modules`, virtual environments, `dist`, `build` and `target` without walking them. Limit any
|
|
68
47
|
command to some collections with `--collection NAME` (repeatable), list them with
|
|
69
48
|
`steersync config collections`, and see [docs/central-layout.md](docs/central-layout.md) for
|
|
70
49
|
a worked example of a full `.kiro/` tree in the central repository.
|
|
71
50
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
51
|
+
Never synced, by design: workspace permissions (`~/.kiro/workspace-roots/<hash>/permissions.yaml`,
|
|
52
|
+
kept per user so that a cloned repository cannot inject permission rules) and
|
|
53
|
+
`~/.kiro/settings/permissions.yaml`, `~/.kiro/powers/` (installed from a registry),
|
|
54
|
+
`~/.kiro/memories/`, `~/.kiro/sessions/`, `~/.kiro/crew/`, `~/.kiro/settings/cli.json`,
|
|
55
|
+
`managed-settings.json` and knowledge base indexes (the declarations in agent `resources`
|
|
56
|
+
are synced with the agent). Every path above comes from
|
|
75
57
|
the Kiro configuration scopes documentation; a new kind of content is one YAML block.
|
|
76
58
|
|
|
77
59
|
## Install
|
|
@@ -81,8 +63,11 @@ Requires Python 3.14 or newer and git 2.18 or newer. Every
|
|
|
81
63
|
sdist and a `SHA256SUMS` file, with signed build provenance.
|
|
82
64
|
|
|
83
65
|
```bash
|
|
84
|
-
VERSION=0.
|
|
66
|
+
VERSION=0.4.0
|
|
85
67
|
uv tool install "https://github.com/SCGIS-Wales/steersync/releases/download/v${VERSION}/steersync-${VERSION}-py3-none-any.whl"
|
|
68
|
+
# or run it without installing
|
|
69
|
+
uvx steersync --help
|
|
70
|
+
uvx --from "steersync[mcp]" steersync-mcp
|
|
86
71
|
# with the MCP server
|
|
87
72
|
uv tool install "steersync[mcp] @ https://github.com/SCGIS-Wales/steersync/releases/download/v${VERSION}/steersync-${VERSION}-py3-none-any.whl"
|
|
88
73
|
# verify where the wheel came from
|
|
@@ -182,10 +167,12 @@ subdirectory; `pull` and `status` print a warning pointing at them until that is
|
|
|
182
167
|
| `steersync init [--write-config] [--hook] [--no-exclude] [--no-kiro] [--mcp-command PATH]` | Prepare a repository: excludes, git hook, Kiro session hook and MCP server entry. |
|
|
183
168
|
| `steersync install-hook [--force]` | Install or update the chaining pre-push hook. |
|
|
184
169
|
| `steersync kiro-hook [--engine v2\|v3] [--write]` | Render a Kiro hook that runs `steersync pull --quiet` at session start. |
|
|
185
|
-
| `steersync
|
|
186
|
-
| `steersync
|
|
170
|
+
| `steersync migrate-hooks [--write]` | Convert `*.kiro.hook` files and CLI 2.x inline agent hooks into `.kiro/hooks/*.json`. Dry run by default; never overwrites or deletes. |
|
|
171
|
+
| `steersync v3-status [--json] [--strict]` | Report the kiro-cli version, `chat.agentEngine` and agents still in the V2 format. `--strict` exits 10 when a reminder applies. |
|
|
172
|
+
| `steersync mcp-config [--command uvx] [--remote URL]` | Render an `mcp.json` fragment. |
|
|
173
|
+
| `steersync mcp` (or `steersync-mcp`) | Run the MCP stdio server. |
|
|
187
174
|
| `steersync config show\|validate\|default\|collections` | Inspect configuration and the resolved collection directories. |
|
|
188
|
-
| `steersync doctor` | Report git version, resolved paths, remote and
|
|
175
|
+
| `steersync doctor` | Report git version, resolved paths, remote, project slug and the Kiro CLI harness. |
|
|
189
176
|
|
|
190
177
|
Global options: `--config PATH`, `--log-level`, `--log-format text|json`, `--quiet`.
|
|
191
178
|
|
|
@@ -290,7 +277,7 @@ Teams that already use [pre-commit](https://pre-commit.com) can use the publishe
|
|
|
290
277
|
default_install_hook_types: [pre-commit, pre-push]
|
|
291
278
|
repos:
|
|
292
279
|
- repo: https://github.com/SCGIS-Wales/steersync
|
|
293
|
-
rev: v0.
|
|
280
|
+
rev: v0.4.0
|
|
294
281
|
hooks:
|
|
295
282
|
- id: steersync-push
|
|
296
283
|
- id: steersync-lint
|
|
@@ -338,9 +325,12 @@ The merge request is opened in two ways:
|
|
|
338
325
|
## Validation
|
|
339
326
|
|
|
340
327
|
Each collection runs one lint profile: `steering`, `agent`, `hooks`, `skill`, `settings`,
|
|
341
|
-
`prompt`, `markdown`, `json` or `generic`. **Errors** are things
|
|
342
|
-
matter after a blank line, an unknown inclusion
|
|
343
|
-
`name` and `description
|
|
328
|
+
`prompt`, `workflow`, `kiroignore`, `markdown`, `json` or `generic`. **Errors** are things
|
|
329
|
+
Kiro cannot read or would rewrite (front matter after a blank line, an unknown inclusion
|
|
330
|
+
mode, invalid JSON, a `SKILL.md` without `name` and `description`, a hook without
|
|
331
|
+
`version: "v1"`, a workflow `repeat` without `maxIterations`, an unknown sandbox
|
|
332
|
+
`networkAccess`, a V2 format agent) or secrets, including literal tokens in `mcp.json`
|
|
333
|
+
`env`, `headers` and `oauth.clientSecret`; they stop a push. **Warnings** are best practices from
|
|
344
334
|
the Kiro documentation, reported objectively and never blocking: a steering file with a
|
|
345
335
|
numeric prefix, an `auto` description that is not written as a trigger, a `globs` key where
|
|
346
336
|
Kiro reads `fileMatchPattern`, an agent with `tools: ["*"]` or a `file://.kiro/steering/**`
|
|
@@ -360,8 +350,22 @@ and `lint.practices: false` turns the warnings off.
|
|
|
360
350
|
fire only in headless runs or with a custom agent active, so treat them as a convenience and
|
|
361
351
|
keep the git hook as the dependable trigger.
|
|
362
352
|
|
|
353
|
+
**Kiro CLI V3.** Kiro CLI 3.0.0 made V3 the default agent harness; V2 still runs but gets no
|
|
354
|
+
new features. `steersync doctor`, `steersync v3-status`, the `kiro_v3_status` MCP tool and
|
|
355
|
+
the session hook (at most once a day) check `kiro-cli --version`, `chat.agentEngine` and your
|
|
356
|
+
agent files. When a reminder applies, run `kiro-cli settings chat.agentEngine v3`, start
|
|
357
|
+
`kiro-cli` and run `/upgrade-agent`; for a shared agent directory run
|
|
358
|
+
`kiro-cli agent upgrade <dir>`. See <https://kiro.dev/docs/cli/v3/>. The probes never start a
|
|
359
|
+
chat, so they use no Kiro credits, and a reminder never fails a sync. Set
|
|
360
|
+
`STEERSYNC_NO_V3_REMINDER=1` to silence the session hook reminder.
|
|
361
|
+
|
|
363
362
|
**MCP server.** `steersync init` registers the server in `.kiro/settings/mcp.json`
|
|
364
|
-
(`steersync mcp-config` prints the fragment).
|
|
363
|
+
(`steersync mcp-config` prints the fragment). It runs through
|
|
364
|
+
`uvx --from "steersync[mcp]==<version>" steersync mcp`, so nothing needs installing, and it
|
|
365
|
+
auto approves only the read only tools. The server is built on the MCP Python SDK v2
|
|
366
|
+
(`MCPServer`, specification 2026-07-28): tools return structured JSON and carry titles and
|
|
367
|
+
read only, destructive and idempotent hints. A forced pull needs `confirm: true` because it
|
|
368
|
+
overwrites local edits. The server tells the agent which tool answers
|
|
365
369
|
which request, so plain sentences work:
|
|
366
370
|
|
|
367
371
|
| Say | Tool |
|
|
@@ -372,6 +376,7 @@ which request, so plain sentences work:
|
|
|
372
376
|
| "what changed", "status", "any open proposals for this repo" | `diff_kiro_config` |
|
|
373
377
|
| "validate / lint / check the kiro config, agents, hooks, skills" | `validate_kiro_config` |
|
|
374
378
|
| "what is synced and where" | `list_kiro_collections` |
|
|
379
|
+
| "am I on Kiro V3", "do my agents need upgrading" | `kiro_v3_status` |
|
|
375
380
|
|
|
376
381
|
Every tool accepts a `collections` list. Kiro does not pass the shell's `PATH`,
|
|
377
382
|
`SSH_AUTH_SOCK`, proxy variables or `GITLAB_TOKEN` to MCP servers, so the rendered entry
|
|
@@ -1,17 +1,20 @@
|
|
|
1
1
|
[build-system]
|
|
2
|
-
requires = ["hatchling>=1.
|
|
2
|
+
requires = ["hatchling>=1.33,<2"]
|
|
3
3
|
build-backend = "hatchling.build"
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "steersync"
|
|
7
7
|
dynamic = ["version"]
|
|
8
|
-
description = "Sync Kiro steering
|
|
8
|
+
description = "Sync Kiro configuration (steering, specs, skills, agents, hooks, workflows, settings) with a central git repository."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
license = "Apache-2.0"
|
|
11
11
|
license-files = ["LICENSE"]
|
|
12
12
|
requires-python = ">=3.14"
|
|
13
13
|
authors = [{ name = "Dejan Gregor", email = "dejan.gregor@gmail.com" }]
|
|
14
|
-
keywords = [
|
|
14
|
+
keywords = [
|
|
15
|
+
"kiro", "kiro-cli", "steering", "agents", "hooks", "workflows", "git", "pre-push", "mcp",
|
|
16
|
+
"developer-experience",
|
|
17
|
+
]
|
|
15
18
|
classifiers = [
|
|
16
19
|
"Development Status :: 4 - Beta",
|
|
17
20
|
"Environment :: Console",
|
|
@@ -20,15 +23,16 @@ classifiers = [
|
|
|
20
23
|
"Programming Language :: Python :: 3",
|
|
21
24
|
"Programming Language :: Python :: 3 :: Only",
|
|
22
25
|
"Programming Language :: Python :: 3.14",
|
|
26
|
+
"Programming Language :: Python :: 3.15",
|
|
23
27
|
"Topic :: Software Development :: Version Control :: Git",
|
|
24
28
|
"Typing :: Typed",
|
|
25
29
|
]
|
|
26
30
|
dependencies = [
|
|
27
|
-
"click>=8.5,<9",
|
|
28
|
-
"pydantic>=2.14,<3",
|
|
31
|
+
"click>=8.5.1,<9",
|
|
32
|
+
"pydantic>=2.14.4,<3",
|
|
29
33
|
"python-frontmatter>=1.3,<2",
|
|
30
|
-
"PyYAML>=6.0.
|
|
31
|
-
"pymarkdownlnt>=0.9.
|
|
34
|
+
"PyYAML>=6.0.4,<7",
|
|
35
|
+
"pymarkdownlnt>=0.9.42,<1",
|
|
32
36
|
]
|
|
33
37
|
|
|
34
38
|
[project.optional-dependencies]
|
|
@@ -36,6 +40,7 @@ mcp = ["mcp>=2.3,<3"]
|
|
|
36
40
|
|
|
37
41
|
[project.scripts]
|
|
38
42
|
steersync = "steersync.cli:run"
|
|
43
|
+
steersync-mcp = "steersync.mcp_server:main"
|
|
39
44
|
|
|
40
45
|
[project.urls]
|
|
41
46
|
Homepage = "https://github.com/SCGIS-Wales/steersync"
|
|
@@ -45,13 +50,13 @@ Changelog = "https://github.com/SCGIS-Wales/steersync/blob/main/CHANGELOG.md"
|
|
|
45
50
|
|
|
46
51
|
[dependency-groups]
|
|
47
52
|
dev = [
|
|
48
|
-
"pytest>=9.
|
|
53
|
+
"pytest>=9.2,<10",
|
|
49
54
|
"pytest-cov>=7.1,<8",
|
|
50
|
-
"ruff>=0.17,<1",
|
|
55
|
+
"ruff>=0.17.6,<1",
|
|
51
56
|
"mypy>=2.4,<3",
|
|
52
57
|
"types-PyYAML>=6.0.12",
|
|
53
|
-
"bandit[toml]>=1.
|
|
54
|
-
"pip-audit>=2.
|
|
58
|
+
"bandit[toml]>=1.9,<2",
|
|
59
|
+
"pip-audit>=2.10,<3",
|
|
55
60
|
"mcp>=2.3,<3",
|
|
56
61
|
]
|
|
57
62
|
|
|
@@ -108,9 +113,10 @@ files = ["src", "tests", "scripts"]
|
|
|
108
113
|
module = ["frontmatter", "frontmatter.*", "pymarkdown.*", "mcp.*"]
|
|
109
114
|
ignore_missing_imports = true
|
|
110
115
|
|
|
111
|
-
[tool.pytest
|
|
116
|
+
[tool.pytest]
|
|
117
|
+
# pytest 9 native TOML configuration.
|
|
112
118
|
testpaths = ["tests"]
|
|
113
|
-
addopts = "-ra --strict-markers --strict-config"
|
|
119
|
+
addopts = ["-ra", "--strict-markers", "--strict-config"]
|
|
114
120
|
xfail_strict = true
|
|
115
121
|
filterwarnings = ["error"]
|
|
116
122
|
|
|
@@ -120,7 +126,7 @@ source = ["steersync"]
|
|
|
120
126
|
omit = ["src/steersync/__main__.py"]
|
|
121
127
|
|
|
122
128
|
[tool.coverage.report]
|
|
123
|
-
fail_under =
|
|
129
|
+
fail_under = 90
|
|
124
130
|
show_missing = true
|
|
125
131
|
skip_covered = false
|
|
126
132
|
exclude_also = ["if TYPE_CHECKING:", "raise NotImplementedError"]
|
|
@@ -18,8 +18,6 @@ Used by the CI workflow on every push to ``main``. The decision is deterministic
|
|
|
18
18
|
Every function is pure apart from ``apply`` so the rules are unit tested.
|
|
19
19
|
"""
|
|
20
20
|
|
|
21
|
-
from __future__ import annotations
|
|
22
|
-
|
|
23
21
|
import argparse
|
|
24
22
|
import datetime as dt
|
|
25
23
|
import re
|