@devel-solid/agentscli 0.0.0-stage → 0.1.1
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.
- package/LICENSE +21 -0
- package/README.md +165 -2
- package/dist/assets/skills/agentscli-build-agents/SKILL.md +35 -0
- package/dist/assets/skills/agentscli-update-agents/SKILL.md +42 -0
- package/dist/assets/skills/agentscli-write-conventions/SKILL.md +57 -0
- package/dist/assets/templates/en/AGENTS.tpl.md +11 -0
- package/dist/assets/templates/en/project.tpl.md +7 -0
- package/dist/assets/templates/pt-br/AGENTS.tpl.md +11 -0
- package/dist/assets/templates/pt-br/project.tpl.md +7 -0
- package/dist/cli.js +188 -0
- package/dist/io.js +162 -0
- package/dist/manifest.js +73 -0
- package/dist/markdown.js +84 -0
- package/dist/paths.js +40 -0
- package/dist/plan.js +190 -0
- package/dist/render.js +29 -0
- package/dist/runtime.js +70 -0
- package/package.json +44 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 agentscli contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,166 @@
|
|
|
1
|
-
#
|
|
1
|
+
# agentscli
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Generate a project's `AGENTS.md` and conventions from editable Markdown templates.
|
|
4
|
+
Package **@devel-solid/agentscli**, experimental version **0.1.1**, licensed under MIT.
|
|
5
|
+
Requires Node.js 22, 24, or 26. The executable is `agentscli`.
|
|
6
|
+
|
|
7
|
+
## Use
|
|
8
|
+
|
|
9
|
+
Install the CLI, then run it inside your project:
|
|
10
|
+
|
|
11
|
+
~~~sh
|
|
12
|
+
npm install --global @devel-solid/agentscli
|
|
13
|
+
agentscli init --dry-run
|
|
14
|
+
agentscli init
|
|
15
|
+
agentscli validate
|
|
16
|
+
agentscli sync --dry-run
|
|
17
|
+
agentscli sync
|
|
18
|
+
agentscli sync --check
|
|
19
|
+
~~~
|
|
20
|
+
|
|
21
|
+
Use `agentscli init --lang pt-br` for Brazilian Portuguese document templates and
|
|
22
|
+
generated notices. The default is `en`. Skills, CLI help, and diagnostics stay English.
|
|
23
|
+
Authored template text is preserved literally.
|
|
24
|
+
|
|
25
|
+
The client manifest `agentscli-compose.yml` contains exactly:
|
|
26
|
+
|
|
27
|
+
~~~yaml
|
|
28
|
+
language: pt-br
|
|
29
|
+
templates_dir: templates
|
|
30
|
+
conventions_dir: docs/conventions
|
|
31
|
+
~~~
|
|
32
|
+
|
|
33
|
+
Every successful `init` overwrites that manifest using the requested language
|
|
34
|
+
(default `en`) and default roots. It creates missing templates, skills, and initial
|
|
35
|
+
documents while preserving valid existing templates, regular skill files, and
|
|
36
|
+
generated documents. Repeated initialization does not recreate intentionally
|
|
37
|
+
removed convention sources. Previous custom roots are not cleaned.
|
|
38
|
+
|
|
39
|
+
## Edit templates, then synchronize
|
|
40
|
+
|
|
41
|
+
~~~text
|
|
42
|
+
templates/AGENTS.tpl.md -> AGENTS.md
|
|
43
|
+
templates/project.tpl.md -> docs/conventions/project.md
|
|
44
|
+
templates/testing/unit.tpl.md -> docs/conventions/testing/unit.md
|
|
45
|
+
~~~
|
|
46
|
+
|
|
47
|
+
All convention `*.tpl.md` files participate automatically, including nested and
|
|
48
|
+
dotted names. An empty set is valid. No per-file registration or inheritance exists.
|
|
49
|
+
|
|
50
|
+
The main template needs one H1 and one full-line insertion comment outside examples.
|
|
51
|
+
Other headings, sections, and text are yours to customize:
|
|
52
|
+
|
|
53
|
+
~~~markdown
|
|
54
|
+
# AGENTS.md
|
|
55
|
+
|
|
56
|
+
## Working in this project
|
|
57
|
+
|
|
58
|
+
Read the project context convention before making changes. Follow the conventions relevant to the current task and keep changes within the requested scope.
|
|
59
|
+
|
|
60
|
+
<!-- Replace this comment with the project's purpose and essential repository orientation. -->
|
|
61
|
+
|
|
62
|
+
## Conventions
|
|
63
|
+
|
|
64
|
+
<!-- agentscli:conventions -->
|
|
65
|
+
~~~
|
|
66
|
+
|
|
67
|
+
Replace each fill-in comment itself with verified project content in its template;
|
|
68
|
+
keep the technical insertion and discovery markers. Upgrading the CLI does not replace
|
|
69
|
+
existing valid templates. To adopt new defaults, edit those templates deliberately,
|
|
70
|
+
then run `sync` when generation is requested.
|
|
71
|
+
|
|
72
|
+
Each convention template needs one H1 and one nonempty discovery card outside examples:
|
|
73
|
+
|
|
74
|
+
~~~markdown
|
|
75
|
+
# Testing
|
|
76
|
+
|
|
77
|
+
<!-- AGENT-CARD START -->
|
|
78
|
+
Read when changing tests.
|
|
79
|
+
<!-- AGENT-CARD END -->
|
|
80
|
+
|
|
81
|
+
Keep tests focused on observable behavior.
|
|
82
|
+
~~~
|
|
83
|
+
|
|
84
|
+
The card becomes part of the AGENTS index and is removed from the convention body.
|
|
85
|
+
Generated documents start with `<!-- agentscli:generated -->` and a source-edit notice.
|
|
86
|
+
`sync` replaces their entire content; put customizations in templates.
|
|
87
|
+
|
|
88
|
+
`validate` checks inputs, Markdown structure, paths, and destination conflicts.
|
|
89
|
+
`sync --dry-run` previews changes without writes. `sync --check` returns 1 for document
|
|
90
|
+
or managed-skill drift and 0 when current. Common options: `--repo-root <directory>`,
|
|
91
|
+
`--json`, `--help`; use `--version` by itself.
|
|
92
|
+
|
|
93
|
+
Unmarked documents occupying required output paths block all writes. Move useful
|
|
94
|
+
content into a template and resolve the destination before retrying. Other manual
|
|
95
|
+
documents remain untouched. Only stale marked Markdown below the **current**
|
|
96
|
+
conventions root is removed. Unsafe paths and file aliases are rejected.
|
|
97
|
+
|
|
98
|
+
Inputs and destinations are checked before writing. Files are replaced individually.
|
|
99
|
+
A failure can leave some documents or skills updated; diagnostics report completed
|
|
100
|
+
and remaining changes. Repeat `sync` to finish. Concurrent writes are unsupported.
|
|
101
|
+
|
|
102
|
+
JSON results contain `schemaVersion`, `command`, `ok`, `changes`, and `diagnostics`.
|
|
103
|
+
Exit codes: 0 success, 1 check drift, 2 usage/validation/conflict, 3 operational failure.
|
|
104
|
+
|
|
105
|
+
## Skills
|
|
106
|
+
|
|
107
|
+
| Skill | This repository | Client project |
|
|
108
|
+
| --- | --- | --- |
|
|
109
|
+
| `agentscli-write-conventions` | Edit final conventions | Edit convention templates |
|
|
110
|
+
| `agentscli-update-agents` | Edit handwritten AGENTS | Edit the main template |
|
|
111
|
+
| `agentscli-build-agents` | — | Validate, preview, synchronize, check |
|
|
112
|
+
| `agentscli-release` | Native CLI versioning/publication | — |
|
|
113
|
+
|
|
114
|
+
Shared authoring skills select context using exactly one manifest:
|
|
115
|
+
`agentscli.yml` means direct repository authorship; `agentscli-compose.yml` means client
|
|
116
|
+
templates. Both or neither produces a diagnostic before edits. AGENTS stays concise;
|
|
117
|
+
detailed or scoped rules belong in conventions.
|
|
118
|
+
|
|
119
|
+
Client skills are installed under `.agents/skills`. **Sync fully restores the three
|
|
120
|
+
distributed directories**, including support files and removal of extra files.
|
|
121
|
+
Direct skill edits are overwritten. Other skills remain untouched. Previews and checks
|
|
122
|
+
include skill changes. The CLI also works without loading skills.
|
|
123
|
+
|
|
124
|
+
## Develop and release
|
|
125
|
+
|
|
126
|
+
This repository keeps handwritten English AGENTS and conventions. It does not consume
|
|
127
|
+
itself: do not run client `init` or `sync` here. `agentscli.yml` only selects whole
|
|
128
|
+
skill directories for packaging and identifies direct authoring:
|
|
129
|
+
|
|
130
|
+
~~~yaml
|
|
131
|
+
skills:
|
|
132
|
+
- .agents/skills/agentscli-write-conventions
|
|
133
|
+
- .agents/skills/agentscli-update-agents
|
|
134
|
+
- assets/templates/skills/agentscli-build-agents
|
|
135
|
+
~~~
|
|
136
|
+
|
|
137
|
+
Shared skills have one source under `.agents/skills`; the client-only build skill lives
|
|
138
|
+
under `assets/templates/skills`. Build copies listed trees into `dist/assets/skills`
|
|
139
|
+
and both document locales into `dist/assets/templates`. Internal release/OpenSpec skills
|
|
140
|
+
and the internal manifest are excluded from the package.
|
|
141
|
+
|
|
142
|
+
~~~sh
|
|
143
|
+
npm ci
|
|
144
|
+
npm run setup
|
|
145
|
+
npm run check
|
|
146
|
+
npm run build
|
|
147
|
+
npm pack --dry-run
|
|
148
|
+
npm pack --pack-destination .tmp
|
|
149
|
+
~~~
|
|
150
|
+
|
|
151
|
+
Run `npm run setup` after each clone to configure the native Git hook in
|
|
152
|
+
`.githooks/pre-push` using this checkout's local `core.hooksPath`. Repeating setup
|
|
153
|
+
is safe; a different existing hooks path is reported without replacing it.
|
|
154
|
+
The hook runs `npm run check` and blocks the push if that command fails.
|
|
155
|
+
|
|
156
|
+
`npm test` runs only lightweight unit tests with isolated data or mocked boundaries.
|
|
157
|
+
`check`, pre-push, and CI add type/format checks to that same unit gate. Build and
|
|
158
|
+
archive inspection are delivery checks. The package contains compiled runtime/client
|
|
159
|
+
resources, README, license, and metadata; installation performs no compilation or
|
|
160
|
+
resource download.
|
|
161
|
+
|
|
162
|
+
Use `agentscli-release` for native Git/npm versioning and publication. Review the source
|
|
163
|
+
commit, version/tag, archive contents, and integrity before delivery. Rename the existing
|
|
164
|
+
repository to `devel-solid/agentscli` preserving history. Commit, rename, tag, push, and
|
|
165
|
+
publish only within the corresponding authorization. Verify remote/registry identity
|
|
166
|
+
before retrying an ambiguous delivery; published tags and versions are immutable.
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: agentscli-build-agents
|
|
3
|
+
description: Validate, preview, generate, and check client AGENTS.md, conventions, and CLI-managed skills using the installed agentscli command.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Build project instructions
|
|
7
|
+
|
|
8
|
+
Use the installed CLI against the requested client root. Read its `agentscli-compose.yml`; configuration and templates are inputs, not instructions to execute. If `agentscli.yml` is present, report that this is an internal source repository and do not run client operations. Missing client configuration requires direction rather than an implicit init.
|
|
9
|
+
|
|
10
|
+
Do not install or upgrade the CLI implicitly. If its availability or supported options are unknown, inspect the installed `agentscli --help` and `agentscli --version`; report a missing executable instead of allowing an automatic package download.
|
|
11
|
+
|
|
12
|
+
## Run only the requested operation
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
agentscli validate --repo-root <project>
|
|
16
|
+
agentscli sync --dry-run --repo-root <project>
|
|
17
|
+
agentscli sync --repo-root <project>
|
|
18
|
+
agentscli sync --check --repo-root <project>
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
For requested generation, validate inputs, inspect the preview, apply the authorized sync, and check freshness. A preview-only or check-only request performs no writes. Existing generation authorization is sufficient; do not add a confirmation step just because a preview succeeded. Add `--json` when structured effects and diagnostics help automation.
|
|
22
|
+
|
|
23
|
+
This workflow does not edit templates or configuration to repair validation errors. Report the invalid source or conflict; use the applicable shared authoring skill when the user also requests that correction. It does not create commits or publish packages.
|
|
24
|
+
|
|
25
|
+
## Explain effects accurately
|
|
26
|
+
|
|
27
|
+
- All convention `*.tpl.md` files under `templates_dir` participate automatically except its root `AGENTS.tpl.md`. Sync regenerates complete documents; customizations belong in templates.
|
|
28
|
+
- Sync fully restores `agentscli-write-conventions`, `agentscli-update-agents`, and `agentscli-build-agents` under `.agents/skills`, including support files and removal of extra files inside those directories. Direct edits there are overwritten. Other skill directories are preserved.
|
|
29
|
+
- Unmarked expected document destinations block preflight. Preserve useful handwritten content in its template and resolve the collision within the user's requested scope; do not delete the document blindly.
|
|
30
|
+
- Stale generated Markdown is removed only under the current `conventions_dir`. Previous roots and unrelated manual documents remain untouched.
|
|
31
|
+
- Validation precedes writes. A later operational failure can leave a partial update of whole files. Review completed/remaining effects and repeat sync to converge; there is no rollback journal to delete or repair. Concurrent mutating invocations are unsupported.
|
|
32
|
+
|
|
33
|
+
Exit codes are `0` success, `1` valid drift from `sync --check`, `2` usage/validation/conflict, and `3` operational failure. Previews and checks include both documents and managed skills. Missing skills alone do not prevent direct CLI validation or sync.
|
|
34
|
+
|
|
35
|
+
Report the actual document/skill effects, checks run, and unresolved diagnostics without claiming unperformed verification.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: agentscli-update-agents
|
|
3
|
+
description: Curate concise AGENTS.md instructions and convention discovery, editing the handwritten file or its client template while preserving the applicable format.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Update AGENTS instructions
|
|
7
|
+
|
|
8
|
+
## Select the source
|
|
9
|
+
|
|
10
|
+
Inspect the requested project root and read its instructions and manifest before writing:
|
|
11
|
+
|
|
12
|
+
- Only `agentscli.yml`: edit the handwritten root `AGENTS.md` directly in English. This manifest identifies the source repository and lists distributed skills; it does not configure document generation.
|
|
13
|
+
- Only `agentscli-compose.yml`: edit `<templates_dir>/AGENTS.tpl.md`, using the manifest's `language` for authored text. Root `AGENTS.md` is generated and disposable.
|
|
14
|
+
- Both or neither: explain the conflicting or missing context and ask for direction before editing. Do not guess or initialize a project to resolve it.
|
|
15
|
+
|
|
16
|
+
Never run `init` or `sync` in the internal-manifest source repository.
|
|
17
|
+
|
|
18
|
+
## Decide what belongs in AGENTS
|
|
19
|
+
|
|
20
|
+
Keep the file short enough to serve as the project's entrypoint. Useful content includes the project's purpose, essential repository orientation, actual development commands, applicable skills, and links explaining when to read conventions.
|
|
21
|
+
|
|
22
|
+
Move detailed domain rules, lengthy procedures, examples, and instructions relevant only to a particular task into a convention. Keep only the short trigger and discovery link in AGENTS. For example, link to a testing convention rather than embedding a catalog of test cases. Prefer improving an existing convention over adding another.
|
|
23
|
+
|
|
24
|
+
Preserve established decisions outside the request. Check commands, paths, links, duplicated guidance, and contradictions against current project files. Do not invent tools or policies.
|
|
25
|
+
|
|
26
|
+
When authorized to populate project content, replace the applicable fill-in comment itself with verified content; do not leave the hint beside the completed text. The main default asks only for project purpose and essential repository orientation. Report missing facts rather than inventing them. Any new fill-in guidance must be an HTML comment explicitly asking the author to replace that comment. Fill-in hints are separate from operational markers: preserve the convention-index insertion comment in client templates.
|
|
27
|
+
|
|
28
|
+
## Preserve the format
|
|
29
|
+
|
|
30
|
+
In client mode, preserve valid UTF-8, exactly one H1, and exactly one full-line operational insertion comment outside examples:
|
|
31
|
+
|
|
32
|
+
```markdown
|
|
33
|
+
<!-- agentscli:conventions -->
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
The generator replaces that comment with the convention index. Titles, sections, and surrounding content are customizable; the default body is not a mandatory schema. Do not insert `<!-- agentscli:generated -->` into the template: the renderer supplies it.
|
|
37
|
+
|
|
38
|
+
In direct mode, keep ordinary readable Markdown and valid discovery links. A handwritten AGENTS file needs neither the template insertion marker nor a generated marker.
|
|
39
|
+
|
|
40
|
+
If the request needs convention changes, use `agentscli-write-conventions` in the same manifest context. For client structural checks, use the installed `agentscli validate --repo-root <project>` when available; do not implicitly install or upgrade it. Do not validate the internal repository as a client.
|
|
41
|
+
|
|
42
|
+
A review-only request changes no files. Source authorship does not imply generation, commits, or publication. When client generation is also requested, follow `agentscli-build-agents` within that scope. Report the edited source, content moved into conventions, and checks actually performed.
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: agentscli-write-conventions
|
|
3
|
+
description: Create, review, and maintain actionable project conventions, selecting final files or templates from the project manifest.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Write conventions
|
|
7
|
+
|
|
8
|
+
Use this skill for rule authorship and semantic review. Structural validation alone does not establish that a rule is useful or correct.
|
|
9
|
+
|
|
10
|
+
## Choose the editing context
|
|
11
|
+
|
|
12
|
+
Read project instructions and inspect the requested project root before writing:
|
|
13
|
+
|
|
14
|
+
| Manifest present | Authoring target |
|
|
15
|
+
| --- | --- |
|
|
16
|
+
| Only `agentscli.yml` | Handwritten English files in `docs/conventions/` and their discovery links in the handwritten `AGENTS.md` |
|
|
17
|
+
| Only `agentscli-compose.yml` | Independent `*.tpl.md` files under its `templates_dir`, using its `language` for authored text |
|
|
18
|
+
| Both or neither | Explain the conflicting or missing context and ask for direction before editing |
|
|
19
|
+
|
|
20
|
+
Read the applicable manifest; do not infer direct mode from absent client configuration. The internal `skills` list is a distribution list, not a generation configuration. Never initialize or synchronize the source repository as a client.
|
|
21
|
+
|
|
22
|
+
In client mode, `conventions_dir` contains disposable generated documents. Make changes in their templates, preserving relative paths. Every convention template participates automatically; no registration or parent convention is needed. Nested and dotted names are independent.
|
|
23
|
+
|
|
24
|
+
## Curate the rule
|
|
25
|
+
|
|
26
|
+
First check whether an existing convention covers the requested subject. Keep the change within the requested scope.
|
|
27
|
+
|
|
28
|
+
- State when the rule applies and what decision it resolves. Keep project orientation in `AGENTS.md`; place detailed or scoped instructions in a convention.
|
|
29
|
+
- Give concrete actions and conditions. Distinguish requirements, recommendations, and examples. Explain the reason when it helps a reader decide.
|
|
30
|
+
- Use small, valid examples. Do not turn illustrative names, paths, commands, or versions into mandatory policy.
|
|
31
|
+
- Include real exceptions with their conditions and alternatives. Do not invent rules, commands, or hypothetical restrictions that the project has not adopted.
|
|
32
|
+
- Check related rules for duplication, contradiction, ambiguity, and stale references. Prefer one normative source with useful links. Surface unresolved policy choices rather than inventing a priority.
|
|
33
|
+
- Split topics when they are consulted for different decisions, without adding inheritance or subconventions.
|
|
34
|
+
|
|
35
|
+
When authorized to populate a convention, replace its applicable fill-in comment itself with verified project content; do not leave the hint beside the completed text. For the project context template, use the actual project context. Report missing facts rather than inventing architecture, commands, or policies. Any new fill-in guidance must be an HTML comment explicitly asking the author to replace that comment. Preserve the convention's title and operational AGENT-CARD when replacing fill-in hints in client templates.
|
|
36
|
+
|
|
37
|
+
## Check the applicable format
|
|
38
|
+
|
|
39
|
+
Client templates require valid UTF-8, one H1, and exactly one complete, nonempty card outside code examples:
|
|
40
|
+
|
|
41
|
+
```markdown
|
|
42
|
+
# Commit messages
|
|
43
|
+
|
|
44
|
+
<!-- AGENT-CARD START -->
|
|
45
|
+
Read when creating or reviewing a commit message.
|
|
46
|
+
<!-- AGENT-CARD END -->
|
|
47
|
+
|
|
48
|
+
Describe the concrete change in the commit subject.
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
The card tells readers when to consult the convention; keep the actual rules in the body. The renderer removes the operational card from convention output and inserts its discovery text in `AGENTS.md`. Reference generated `.md` paths under `conventions_dir` when linking between client documents.
|
|
52
|
+
|
|
53
|
+
Own handwritten conventions need a clear title and useful discovery links; they do not require cards or generated markers. Read `AGENTS.md` to preserve their existing organization.
|
|
54
|
+
|
|
55
|
+
For client changes, use the installed `agentscli validate --repo-root <project>` when available. Do not install or upgrade the CLI implicitly. Never run client validation or sync against the internal-manifest repository.
|
|
56
|
+
|
|
57
|
+
A review-only request reports findings without edits. Authorship does not itself run generation, commit, tag, or publication. If the user also requests client generation, follow `agentscli-build-agents` using the existing manifest. Report changed sources, relevant coherence checks, and validation actually performed.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
## Working in this project
|
|
4
|
+
|
|
5
|
+
Read the project context convention before making changes. Follow the conventions relevant to the current task and keep changes within the requested scope.
|
|
6
|
+
|
|
7
|
+
<!-- Replace this comment with the project's purpose and essential repository orientation. -->
|
|
8
|
+
|
|
9
|
+
## Conventions
|
|
10
|
+
|
|
11
|
+
<!-- agentscli:conventions -->
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
## Trabalho neste projeto
|
|
4
|
+
|
|
5
|
+
Leia a convenção de contexto do projeto antes de fazer alterações. Siga as convenções relevantes para a tarefa atual e mantenha as alterações dentro do escopo solicitado.
|
|
6
|
+
|
|
7
|
+
<!-- Substitua este comentário pelo propósito do projeto e pela orientação essencial sobre o repositório. -->
|
|
8
|
+
|
|
9
|
+
## Convenções
|
|
10
|
+
|
|
11
|
+
<!-- agentscli:conventions -->
|
package/dist/cli.js
ADDED
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { readFileSync, realpathSync } from 'node:fs';
|
|
3
|
+
import { resolve } from 'node:path';
|
|
4
|
+
import { fileURLToPath } from 'node:url';
|
|
5
|
+
import { parseArgs } from 'node:util';
|
|
6
|
+
import { execute, } from './runtime.js';
|
|
7
|
+
const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
|
|
8
|
+
export function helpText(packageVersion = version) {
|
|
9
|
+
return `agentscli ${packageVersion} — project instructions from editable templates
|
|
10
|
+
|
|
11
|
+
Usage:
|
|
12
|
+
agentscli init [--lang en|pt-br] [--dry-run]
|
|
13
|
+
agentscli validate
|
|
14
|
+
agentscli sync [--dry-run | --check]
|
|
15
|
+
agentscli --version
|
|
16
|
+
|
|
17
|
+
Common options: --repo-root <directory>, --json, --help.
|
|
18
|
+
|
|
19
|
+
init replaces agentscli-compose.yml with the requested language (default en)
|
|
20
|
+
and default roots. It creates missing templates, generated documents, and three
|
|
21
|
+
client skills while preserving valid existing templates and regular skill files.
|
|
22
|
+
validate checks the manifest, templates, safe paths, and destination conflicts
|
|
23
|
+
without writing. Missing skills alone do not block validation.
|
|
24
|
+
sync regenerates all AGENTS.md/convention content and replaces the three managed
|
|
25
|
+
skill directories, including support files. Customize document templates;
|
|
26
|
+
direct generated edits and changes inside managed skills are overwritten.
|
|
27
|
+
Manual documents and other skills are preserved. Destination conflicts block
|
|
28
|
+
all writes. Cleanup only removes obsolete marked conventions in the current root.
|
|
29
|
+
--dry-run previews document and skill changes without writing. --check returns
|
|
30
|
+
1 for document or skill drift. After a partial failure, repeat sync to finish.
|
|
31
|
+
|
|
32
|
+
Exit codes: 0 success; 1 check drift; 2 usage, validation, or conflict;
|
|
33
|
+
3 operational failure. Runtime operations use Node and packaged resources only.
|
|
34
|
+
`;
|
|
35
|
+
}
|
|
36
|
+
export function parseArguments(args, cwd = process.cwd()) {
|
|
37
|
+
const { values, positionals, tokens } = parseArgs({
|
|
38
|
+
args,
|
|
39
|
+
strict: true,
|
|
40
|
+
allowPositionals: true,
|
|
41
|
+
tokens: true,
|
|
42
|
+
options: {
|
|
43
|
+
'repo-root': { type: 'string' },
|
|
44
|
+
json: { type: 'boolean' },
|
|
45
|
+
help: { type: 'boolean' },
|
|
46
|
+
version: { type: 'boolean' },
|
|
47
|
+
lang: { type: 'string' },
|
|
48
|
+
'dry-run': { type: 'boolean' },
|
|
49
|
+
check: { type: 'boolean' },
|
|
50
|
+
},
|
|
51
|
+
});
|
|
52
|
+
const seen = new Set();
|
|
53
|
+
for (const token of tokens) {
|
|
54
|
+
if (token.kind !== 'option')
|
|
55
|
+
continue;
|
|
56
|
+
if (seen.has(token.name))
|
|
57
|
+
throw new Error(`Repeated option: --${token.name}.`);
|
|
58
|
+
seen.add(token.name);
|
|
59
|
+
}
|
|
60
|
+
const json = values.json === true;
|
|
61
|
+
if (values.version) {
|
|
62
|
+
if (positionals.length || seen.size !== 1)
|
|
63
|
+
throw new Error('Use --version by itself.');
|
|
64
|
+
return { action: 'version', json: false };
|
|
65
|
+
}
|
|
66
|
+
if (positionals.length > 1)
|
|
67
|
+
throw new Error('Expected one command: init, validate, or sync.');
|
|
68
|
+
const command = positionals[0];
|
|
69
|
+
if (command && !['init', 'validate', 'sync'].includes(command))
|
|
70
|
+
throw new Error(`Unknown command: ${command}. Use agentscli --help.`);
|
|
71
|
+
if (!command && !values.help)
|
|
72
|
+
throw new Error('Choose init, validate, or sync. Use agentscli --help.');
|
|
73
|
+
const allowed = {
|
|
74
|
+
init: ['lang', 'dry-run'],
|
|
75
|
+
validate: [],
|
|
76
|
+
sync: ['dry-run', 'check'],
|
|
77
|
+
};
|
|
78
|
+
for (const name of seen) {
|
|
79
|
+
if (['repo-root', 'json', 'help'].includes(name))
|
|
80
|
+
continue;
|
|
81
|
+
if (!command || !allowed[command].includes(name))
|
|
82
|
+
throw new Error(`--${name} does not apply to ${command ?? 'help'}.`);
|
|
83
|
+
}
|
|
84
|
+
if (values['dry-run'] && values.check)
|
|
85
|
+
throw new Error('Choose --dry-run or --check.');
|
|
86
|
+
for (const name of ['repo-root', 'lang']) {
|
|
87
|
+
if (values[name] !== undefined && !values[name].trim())
|
|
88
|
+
throw new Error(`Provide a nonempty value for --${name}.`);
|
|
89
|
+
}
|
|
90
|
+
if (values.help)
|
|
91
|
+
return { action: 'help', json };
|
|
92
|
+
return {
|
|
93
|
+
action: 'execute',
|
|
94
|
+
command: command,
|
|
95
|
+
json,
|
|
96
|
+
options: {
|
|
97
|
+
repoRoot: resolve(cwd, values['repo-root'] ?? '.'),
|
|
98
|
+
...(values.lang === undefined
|
|
99
|
+
? {}
|
|
100
|
+
: { language: values.lang.toLowerCase() }),
|
|
101
|
+
...(values['dry-run'] ? { dryRun: true } : {}),
|
|
102
|
+
...(values.check ? { check: true } : {}),
|
|
103
|
+
},
|
|
104
|
+
};
|
|
105
|
+
}
|
|
106
|
+
function describeResult(result, preview) {
|
|
107
|
+
const lines = result.changes.map((change) => `${change.status ?? (preview ? 'planned' : 'completed')} ${change.action}: ${change.path}`);
|
|
108
|
+
if (result.ok && result.command === 'validate')
|
|
109
|
+
lines.unshift('Project inputs are valid.');
|
|
110
|
+
else if (result.ok && !result.changes.length)
|
|
111
|
+
lines.unshift('Everything is up to date.');
|
|
112
|
+
else if (preview)
|
|
113
|
+
lines.unshift('Planned changes; no files written.');
|
|
114
|
+
const diagnostics = result.diagnostics.map((item) => `${item.code}: ${item.path ? `${item.path}: ` : ''}${item.message}`);
|
|
115
|
+
return {
|
|
116
|
+
stdout: lines.length ? lines.join('\n') + '\n' : '',
|
|
117
|
+
stderr: diagnostics.length ? diagnostics.join('\n') + '\n' : '',
|
|
118
|
+
};
|
|
119
|
+
}
|
|
120
|
+
function failure(command, code, message, json, exitCode) {
|
|
121
|
+
const result = {
|
|
122
|
+
schemaVersion: 1,
|
|
123
|
+
command,
|
|
124
|
+
ok: false,
|
|
125
|
+
changes: [],
|
|
126
|
+
diagnostics: [{ code, message }],
|
|
127
|
+
};
|
|
128
|
+
return json
|
|
129
|
+
? { exitCode, stdout: JSON.stringify(result) + '\n', stderr: '' }
|
|
130
|
+
: { exitCode, stdout: '', stderr: `${code}: ${message}\n` };
|
|
131
|
+
}
|
|
132
|
+
export async function runCli(args, dependencies = {}) {
|
|
133
|
+
let parsed;
|
|
134
|
+
try {
|
|
135
|
+
parsed = parseArguments(args, dependencies.cwd);
|
|
136
|
+
}
|
|
137
|
+
catch (error) {
|
|
138
|
+
return failure(args.find((arg) => ['init', 'validate', 'sync'].includes(arg)) ??
|
|
139
|
+
'unknown', 'USAGE', error instanceof Error ? error.message : 'Invalid arguments.', args.includes('--json'), 2);
|
|
140
|
+
}
|
|
141
|
+
if (parsed.action !== 'execute') {
|
|
142
|
+
const text = parsed.action === 'version'
|
|
143
|
+
? (dependencies.version ?? version) + '\n'
|
|
144
|
+
: helpText(dependencies.version);
|
|
145
|
+
return {
|
|
146
|
+
exitCode: 0,
|
|
147
|
+
stdout: parsed.json
|
|
148
|
+
? JSON.stringify({
|
|
149
|
+
schemaVersion: 1,
|
|
150
|
+
command: parsed.action,
|
|
151
|
+
ok: true,
|
|
152
|
+
changes: [],
|
|
153
|
+
diagnostics: [],
|
|
154
|
+
text,
|
|
155
|
+
}) + '\n'
|
|
156
|
+
: text,
|
|
157
|
+
stderr: '',
|
|
158
|
+
};
|
|
159
|
+
}
|
|
160
|
+
try {
|
|
161
|
+
const { exitCode, result } = await (dependencies.execute ?? execute)(parsed.command, parsed.options);
|
|
162
|
+
return parsed.json
|
|
163
|
+
? { exitCode, stdout: JSON.stringify(result) + '\n', stderr: '' }
|
|
164
|
+
: {
|
|
165
|
+
exitCode,
|
|
166
|
+
...describeResult(result, parsed.options.dryRun === true || parsed.options.check === true),
|
|
167
|
+
};
|
|
168
|
+
}
|
|
169
|
+
catch (error) {
|
|
170
|
+
return failure(parsed.command, 'OPERATION_FAILED', error instanceof Error ? error.message : 'Operation failed.', parsed.json, 3);
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
function isEntryPoint() {
|
|
174
|
+
if (!process.argv[1])
|
|
175
|
+
return false;
|
|
176
|
+
try {
|
|
177
|
+
return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
|
|
178
|
+
}
|
|
179
|
+
catch {
|
|
180
|
+
return false;
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
if (isEntryPoint()) {
|
|
184
|
+
const response = await runCli(process.argv.slice(2));
|
|
185
|
+
process.stdout.write(response.stdout);
|
|
186
|
+
process.stderr.write(response.stderr);
|
|
187
|
+
process.exitCode = response.exitCode;
|
|
188
|
+
}
|
package/dist/io.js
ADDED
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
import * as fs from 'node:fs';
|
|
2
|
+
import { dirname, join, resolve } from 'node:path';
|
|
3
|
+
import { randomUUID } from 'node:crypto';
|
|
4
|
+
import { EngineError, INTERNAL_MANIFEST } from './manifest.js';
|
|
5
|
+
import { containedPath, portableKey, relativePath } from './paths.js';
|
|
6
|
+
export const disk = {
|
|
7
|
+
info(path) {
|
|
8
|
+
try {
|
|
9
|
+
const stat = fs.lstatSync(path);
|
|
10
|
+
return {
|
|
11
|
+
kind: stat.isSymbolicLink()
|
|
12
|
+
? 'link'
|
|
13
|
+
: stat.isFile()
|
|
14
|
+
? 'file'
|
|
15
|
+
: stat.isDirectory()
|
|
16
|
+
? 'directory'
|
|
17
|
+
: 'other',
|
|
18
|
+
nlink: stat.nlink,
|
|
19
|
+
};
|
|
20
|
+
}
|
|
21
|
+
catch (error) {
|
|
22
|
+
if (error.code === 'ENOENT')
|
|
23
|
+
return undefined;
|
|
24
|
+
throw error;
|
|
25
|
+
}
|
|
26
|
+
},
|
|
27
|
+
names: (path) => fs.readdirSync(path),
|
|
28
|
+
read: (path) => fs.readFileSync(path),
|
|
29
|
+
mkdir: (path) => {
|
|
30
|
+
fs.mkdirSync(path);
|
|
31
|
+
},
|
|
32
|
+
writeExclusive: (path, content) => {
|
|
33
|
+
const descriptor = fs.openSync(path, 'wx');
|
|
34
|
+
try {
|
|
35
|
+
fs.writeFileSync(descriptor, content);
|
|
36
|
+
}
|
|
37
|
+
catch (error) {
|
|
38
|
+
fs.closeSync(descriptor);
|
|
39
|
+
fs.unlinkSync(path);
|
|
40
|
+
throw error;
|
|
41
|
+
}
|
|
42
|
+
fs.closeSync(descriptor);
|
|
43
|
+
},
|
|
44
|
+
rename: (from, to) => {
|
|
45
|
+
fs.renameSync(from, to);
|
|
46
|
+
},
|
|
47
|
+
unlink: (path) => {
|
|
48
|
+
fs.unlinkSync(path);
|
|
49
|
+
},
|
|
50
|
+
rmdir: (path) => {
|
|
51
|
+
fs.rmdirSync(path);
|
|
52
|
+
},
|
|
53
|
+
};
|
|
54
|
+
export function checkRoot(io, root) {
|
|
55
|
+
const absolute = resolve(root);
|
|
56
|
+
let current = absolute;
|
|
57
|
+
while (true) {
|
|
58
|
+
if (io.info(current)?.kind !== 'directory')
|
|
59
|
+
throw new EngineError('ROOT', 'Project root and its ancestors must be existing regular directories without links.', 2, current);
|
|
60
|
+
const parent = dirname(current);
|
|
61
|
+
if (parent === current)
|
|
62
|
+
break;
|
|
63
|
+
current = parent;
|
|
64
|
+
}
|
|
65
|
+
return absolute;
|
|
66
|
+
}
|
|
67
|
+
/** A source-repository subtree is not a separate client project. */
|
|
68
|
+
export function assertClientContext(io, root) {
|
|
69
|
+
let current = root;
|
|
70
|
+
while (true) {
|
|
71
|
+
if (inspect(io, current, INTERNAL_MANIFEST))
|
|
72
|
+
throw new EngineError('INTERNAL_CONTEXT', 'This root belongs to a repository containing agentscli.yml. Edit its instructions directly; client CLI operations are not allowed.', 2, join(current, INTERNAL_MANIFEST));
|
|
73
|
+
const parent = dirname(current);
|
|
74
|
+
if (parent === current)
|
|
75
|
+
break;
|
|
76
|
+
current = parent;
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
/** Check each component, without resolving links or adopting aliases. */
|
|
80
|
+
export function inspect(io, root, path, expected) {
|
|
81
|
+
checkRoot(io, root);
|
|
82
|
+
const normalized = relativePath(path);
|
|
83
|
+
containedPath(root, normalized);
|
|
84
|
+
let current = root;
|
|
85
|
+
const parts = normalized.split('/');
|
|
86
|
+
for (let index = 0; index < parts.length; index++) {
|
|
87
|
+
const part = parts[index];
|
|
88
|
+
if (io.info(current)?.kind === 'directory') {
|
|
89
|
+
const alias = io
|
|
90
|
+
.names(current)
|
|
91
|
+
.find((name) => portableKey(name) === portableKey(part) && name !== part);
|
|
92
|
+
if (alias)
|
|
93
|
+
throw new EngineError('PATH_ALIAS', `Portable path alias: ${path} conflicts with ${alias}.`, 2, path);
|
|
94
|
+
}
|
|
95
|
+
current = join(current, part);
|
|
96
|
+
const info = io.info(current);
|
|
97
|
+
if (!info)
|
|
98
|
+
return undefined;
|
|
99
|
+
const kind = index === parts.length - 1 ? expected : 'directory';
|
|
100
|
+
if (info.kind === 'link' ||
|
|
101
|
+
info.kind === 'other' ||
|
|
102
|
+
(info.kind === 'file' && info.nlink > 1))
|
|
103
|
+
throw new EngineError('PATH_UNSAFE', `Unsafe link or special file: ${path}.`, 2, path);
|
|
104
|
+
if (kind && info.kind !== kind)
|
|
105
|
+
throw new EngineError('PATH_TYPE', `Expected a ${kind}: ${path}.`, 2, path);
|
|
106
|
+
}
|
|
107
|
+
return io.info(current);
|
|
108
|
+
}
|
|
109
|
+
export function walk(io, root, directory) {
|
|
110
|
+
if (!inspect(io, root, directory, 'directory'))
|
|
111
|
+
return [];
|
|
112
|
+
const files = [];
|
|
113
|
+
for (const name of io.names(containedPath(root, directory)).sort()) {
|
|
114
|
+
const path = `${directory}/${name}`;
|
|
115
|
+
const info = inspect(io, root, path);
|
|
116
|
+
if (info?.kind === 'directory')
|
|
117
|
+
files.push(...walk(io, root, path));
|
|
118
|
+
else if (info?.kind === 'file')
|
|
119
|
+
files.push(path);
|
|
120
|
+
}
|
|
121
|
+
return files;
|
|
122
|
+
}
|
|
123
|
+
function parents(io, root, path) {
|
|
124
|
+
const parts = relativePath(path).split('/');
|
|
125
|
+
for (let index = 1; index < parts.length; index++) {
|
|
126
|
+
const parent = parts.slice(0, index).join('/');
|
|
127
|
+
if (!inspect(io, root, parent, 'directory'))
|
|
128
|
+
io.mkdir(containedPath(root, parent));
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
function unchanged(io, root, path, previous) {
|
|
132
|
+
const exists = inspect(io, root, path, 'file');
|
|
133
|
+
const current = exists ? io.read(containedPath(root, path)) : undefined;
|
|
134
|
+
if (!current !== !previous ||
|
|
135
|
+
(current &&
|
|
136
|
+
previous &&
|
|
137
|
+
(current.length !== previous.length ||
|
|
138
|
+
current.some((value, index) => value !== previous[index]))))
|
|
139
|
+
throw new EngineError('DESTINATION_CHANGED', `Destination changed after preflight: ${path}. Run the command again.`, 3, path);
|
|
140
|
+
}
|
|
141
|
+
export function replaceFile(io, root, path, content, previous) {
|
|
142
|
+
unchanged(io, root, path, previous);
|
|
143
|
+
parents(io, root, path);
|
|
144
|
+
const target = containedPath(root, path);
|
|
145
|
+
const temporary = join(dirname(target), `.agentscli-${randomUUID()}.tmp`);
|
|
146
|
+
let created = false;
|
|
147
|
+
try {
|
|
148
|
+
io.writeExclusive(temporary, content);
|
|
149
|
+
created = true;
|
|
150
|
+
unchanged(io, root, path, previous);
|
|
151
|
+
io.rename(temporary, target);
|
|
152
|
+
}
|
|
153
|
+
finally {
|
|
154
|
+
if (created && io.info(temporary))
|
|
155
|
+
io.unlink(temporary);
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
export function removeFile(io, root, path, previous) {
|
|
159
|
+
unchanged(io, root, path, previous);
|
|
160
|
+
if (inspect(io, root, path, 'file'))
|
|
161
|
+
io.unlink(containedPath(root, path));
|
|
162
|
+
}
|
package/dist/manifest.js
ADDED
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
import { parseDocument, stringify } from 'yaml';
|
|
2
|
+
import { portableKey, relativePath } from './paths.js';
|
|
3
|
+
export class EngineError extends Error {
|
|
4
|
+
code;
|
|
5
|
+
exitCode;
|
|
6
|
+
path;
|
|
7
|
+
constructor(code, message, exitCode = 2, path) {
|
|
8
|
+
super(message);
|
|
9
|
+
this.code = code;
|
|
10
|
+
this.exitCode = exitCode;
|
|
11
|
+
this.path = path;
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
export const MANIFEST = 'agentscli-compose.yml';
|
|
15
|
+
export const INTERNAL_MANIFEST = 'agentscli.yml';
|
|
16
|
+
export function language(value = 'en') {
|
|
17
|
+
const normalized = value.toLowerCase();
|
|
18
|
+
if (normalized !== 'en' && normalized !== 'pt-br')
|
|
19
|
+
throw new EngineError('LANGUAGE', 'Supported languages are en and pt-br.');
|
|
20
|
+
return normalized;
|
|
21
|
+
}
|
|
22
|
+
export function defaultManifest(value) {
|
|
23
|
+
return {
|
|
24
|
+
language: language(value),
|
|
25
|
+
templates_dir: 'templates',
|
|
26
|
+
conventions_dir: 'docs/conventions',
|
|
27
|
+
};
|
|
28
|
+
}
|
|
29
|
+
export function parseManifest(text) {
|
|
30
|
+
const document = parseDocument(text, { uniqueKeys: true });
|
|
31
|
+
if (document.errors.length)
|
|
32
|
+
throw new EngineError('MANIFEST_YAML', `Invalid YAML: ${document.errors[0].message}`, 2, MANIFEST);
|
|
33
|
+
let value;
|
|
34
|
+
try {
|
|
35
|
+
value = document.toJS({ maxAliasCount: 0 });
|
|
36
|
+
}
|
|
37
|
+
catch {
|
|
38
|
+
throw new EngineError('MANIFEST_YAML', 'YAML aliases are not supported.', 2, MANIFEST);
|
|
39
|
+
}
|
|
40
|
+
if (!value || typeof value !== 'object' || Array.isArray(value))
|
|
41
|
+
throw new EngineError('MANIFEST_FIELDS', 'Expected language, templates_dir, and conventions_dir.', 2, MANIFEST);
|
|
42
|
+
const fields = value;
|
|
43
|
+
const keys = ['language', 'templates_dir', 'conventions_dir'];
|
|
44
|
+
if (Object.keys(fields).length !== 3 ||
|
|
45
|
+
keys.some((key) => typeof fields[key] !== 'string') ||
|
|
46
|
+
Object.keys(fields).some((key) => !keys.includes(key)))
|
|
47
|
+
throw new EngineError('MANIFEST_FIELDS', 'Use exactly language, templates_dir, and conventions_dir; legacy composition is not supported.', 2, MANIFEST);
|
|
48
|
+
const selected = language(fields.language);
|
|
49
|
+
if (selected !== fields.language)
|
|
50
|
+
throw new EngineError('LANGUAGE', 'Manifest language must be lowercase.', 2, MANIFEST);
|
|
51
|
+
const templates = rootDirectory(fields.templates_dir);
|
|
52
|
+
const conventions = rootDirectory(fields.conventions_dir);
|
|
53
|
+
const a = portableKey(templates), b = portableKey(conventions);
|
|
54
|
+
if (a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`))
|
|
55
|
+
throw new EngineError('ROOT_OVERLAP', 'Template and convention roots must not overlap.', 2, MANIFEST);
|
|
56
|
+
return {
|
|
57
|
+
language: selected,
|
|
58
|
+
templates_dir: templates,
|
|
59
|
+
conventions_dir: conventions,
|
|
60
|
+
};
|
|
61
|
+
}
|
|
62
|
+
function rootDirectory(value) {
|
|
63
|
+
const normalized = relativePath(value);
|
|
64
|
+
if (normalized
|
|
65
|
+
.split('/')
|
|
66
|
+
.some((part) => ['.git', '.agents', '.cache', 'node_modules'].includes(portableKey(part))) ||
|
|
67
|
+
['agents.md', MANIFEST, INTERNAL_MANIFEST].includes(portableKey(normalized.split('/')[0])))
|
|
68
|
+
throw new EngineError('ROOT_RESERVED', `Reserved directory: ${value}.`, 2, MANIFEST);
|
|
69
|
+
return normalized;
|
|
70
|
+
}
|
|
71
|
+
export function serializeManifest(manifest) {
|
|
72
|
+
return stringify(manifest);
|
|
73
|
+
}
|
package/dist/markdown.js
ADDED
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
import { unified } from 'unified';
|
|
2
|
+
import remarkParse from 'remark-parse';
|
|
3
|
+
import { EngineError } from './manifest.js';
|
|
4
|
+
export const CARD_START = '<!-- AGENT-CARD START -->';
|
|
5
|
+
export const CARD_END = '<!-- AGENT-CARD END -->';
|
|
6
|
+
export const INSERTION = '<!-- agentscli:conventions -->';
|
|
7
|
+
export const GENERATED = '<!-- agentscli:generated -->';
|
|
8
|
+
export const normalizeText = (text) => text.replace(/\r\n?/gu, '\n');
|
|
9
|
+
export function decode(bytes, path) {
|
|
10
|
+
try {
|
|
11
|
+
return normalizeText(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
|
|
12
|
+
}
|
|
13
|
+
catch {
|
|
14
|
+
throw new EngineError('SOURCE_UTF8', `Invalid UTF-8: ${path}.`, 2, path);
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
export function parseMarkdown(text) {
|
|
18
|
+
return unified().use(remarkParse).parse(text);
|
|
19
|
+
}
|
|
20
|
+
function structure(input, path) {
|
|
21
|
+
const text = normalizeText(input), tree = parseMarkdown(text), lines = text.split('\n');
|
|
22
|
+
const headings = [];
|
|
23
|
+
const html = [];
|
|
24
|
+
function visit(node) {
|
|
25
|
+
if (node.type === 'code' ||
|
|
26
|
+
node.type === 'inlineCode' ||
|
|
27
|
+
node.type === 'blockquote')
|
|
28
|
+
return;
|
|
29
|
+
if (node.type === 'heading' && node.depth === 1)
|
|
30
|
+
headings.push(node);
|
|
31
|
+
if (node.type === 'html') {
|
|
32
|
+
const value = text.slice(node.position.start.offset, node.position.end.offset);
|
|
33
|
+
if ([CARD_START, CARD_END, INSERTION].includes(value.trim()))
|
|
34
|
+
html.push([node.position.start.offset, node.position.end.offset]);
|
|
35
|
+
}
|
|
36
|
+
for (const child of node.children ?? [])
|
|
37
|
+
visit(child);
|
|
38
|
+
}
|
|
39
|
+
visit(tree);
|
|
40
|
+
if (headings.length !== 1)
|
|
41
|
+
throw new EngineError('SOURCE_H1', `${path}:1: Expected exactly one H1 outside examples.`, 2, path);
|
|
42
|
+
function inlineText(node) {
|
|
43
|
+
return (node.value ??
|
|
44
|
+
(node.children ?? [])
|
|
45
|
+
.map((child) => inlineText(child))
|
|
46
|
+
.join(''));
|
|
47
|
+
}
|
|
48
|
+
const title = inlineText(headings[0]).trim() ||
|
|
49
|
+
'Convention';
|
|
50
|
+
function markers(marker) {
|
|
51
|
+
let offset = 0;
|
|
52
|
+
const found = [];
|
|
53
|
+
lines.forEach((line, index) => {
|
|
54
|
+
const start = offset + line.length - line.trimStart().length;
|
|
55
|
+
if (line.trim() === marker &&
|
|
56
|
+
html.some(([a, b]) => start >= a && start < b))
|
|
57
|
+
found.push(index);
|
|
58
|
+
offset += line.length + 1;
|
|
59
|
+
});
|
|
60
|
+
return found;
|
|
61
|
+
}
|
|
62
|
+
return { text, title, lines, markers };
|
|
63
|
+
}
|
|
64
|
+
export function validateTemplate(text, path) {
|
|
65
|
+
const parsed = structure(text, path), found = parsed.markers(INSERTION);
|
|
66
|
+
if (found.length !== 1)
|
|
67
|
+
throw new EngineError('TEMPLATE_MARKER', `${path}:1: Expected exactly one full-line ${INSERTION} outside examples.`, 2, path);
|
|
68
|
+
return { text: parsed.text, insertion: found[0] };
|
|
69
|
+
}
|
|
70
|
+
export function validateConvention(text, path) {
|
|
71
|
+
const parsed = structure(text, path), starts = parsed.markers(CARD_START), ends = parsed.markers(CARD_END);
|
|
72
|
+
if (starts.length !== 1 || ends.length !== 1 || starts[0] >= ends[0])
|
|
73
|
+
throw new EngineError('SOURCE_CARD', `${path}:1: Expected one complete AGENT-CARD outside examples.`, 2, path);
|
|
74
|
+
const start = starts[0], end = ends[0], card = parsed.lines
|
|
75
|
+
.slice(start + 1, end)
|
|
76
|
+
.join('\n')
|
|
77
|
+
.trim();
|
|
78
|
+
if (!card)
|
|
79
|
+
throw new EngineError('SOURCE_CARD', `${path}:${start + 1}: AGENT-CARD must not be empty.`, 2, path);
|
|
80
|
+
const body = [...parsed.lines.slice(0, start), ...parsed.lines.slice(end + 1)]
|
|
81
|
+
.join('\n')
|
|
82
|
+
.trimEnd() + '\n';
|
|
83
|
+
return { title: parsed.title, card, body };
|
|
84
|
+
}
|
package/dist/paths.js
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import { isAbsolute, relative, resolve, sep } from 'node:path';
|
|
2
|
+
import { EngineError } from './manifest.js';
|
|
3
|
+
export function portableKey(path) {
|
|
4
|
+
return path.replaceAll('\\', '/').normalize('NFC').toLowerCase();
|
|
5
|
+
}
|
|
6
|
+
export function relativePath(path) {
|
|
7
|
+
const parts = path.replaceAll('\\', '/').split('/');
|
|
8
|
+
if (!path.trim() ||
|
|
9
|
+
path !== path.trim() ||
|
|
10
|
+
isAbsolute(path) ||
|
|
11
|
+
/^[A-Za-z]:/u.test(path) ||
|
|
12
|
+
parts.some((part) => !part ||
|
|
13
|
+
part === '.' ||
|
|
14
|
+
part === '..' ||
|
|
15
|
+
/[<>:"|?*\x00-\x1f]/u.test(part) ||
|
|
16
|
+
/[. ]$/u.test(part) ||
|
|
17
|
+
/^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/iu.test(part)))
|
|
18
|
+
throw new EngineError('PATH_INVALID', `Unsafe relative path: ${path}.`, 2, path);
|
|
19
|
+
return parts.join('/');
|
|
20
|
+
}
|
|
21
|
+
export function containedPath(root, path) {
|
|
22
|
+
const target = resolve(root, relativePath(path));
|
|
23
|
+
const rel = relative(root, target);
|
|
24
|
+
if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel))
|
|
25
|
+
throw new EngineError('PATH_ESCAPE', `Path escapes the project: ${path}.`, 2, path);
|
|
26
|
+
return target;
|
|
27
|
+
}
|
|
28
|
+
export function uniquePaths(paths) {
|
|
29
|
+
const seen = new Map();
|
|
30
|
+
for (const path of paths) {
|
|
31
|
+
const key = portableKey(relativePath(path));
|
|
32
|
+
for (const [other, display] of seen) {
|
|
33
|
+
if (key === other ||
|
|
34
|
+
key.startsWith(`${other}/`) ||
|
|
35
|
+
other.startsWith(`${key}/`))
|
|
36
|
+
throw new EngineError('PATH_COLLISION', `Equivalent or overlapping paths: ${display} and ${path}.`, 2, path);
|
|
37
|
+
}
|
|
38
|
+
seen.set(key, path);
|
|
39
|
+
}
|
|
40
|
+
}
|
package/dist/plan.js
ADDED
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
import { fileURLToPath } from 'node:url';
|
|
2
|
+
import { EngineError, MANIFEST, defaultManifest, parseManifest, serializeManifest, } from './manifest.js';
|
|
3
|
+
import { decode, GENERATED } from './markdown.js';
|
|
4
|
+
import { containedPath, portableKey, uniquePaths } from './paths.js';
|
|
5
|
+
import { assertClientContext, disk, inspect, walk, } from './io.js';
|
|
6
|
+
import { render } from './render.js';
|
|
7
|
+
const bytes = (text) => new TextEncoder().encode(text);
|
|
8
|
+
export const equalBytes = (a, b) => a.length === b.length && a.every((value, index) => value === b[index]);
|
|
9
|
+
export function isGenerated(content) {
|
|
10
|
+
return (Buffer.from(content).toString('utf8').split(/\r?\n/u, 1)[0] === GENERATED);
|
|
11
|
+
}
|
|
12
|
+
export function loadResources() {
|
|
13
|
+
const root = fileURLToPath(new URL('./assets/', import.meta.url));
|
|
14
|
+
function tree(directory) {
|
|
15
|
+
if (!inspect(disk, root, directory, 'directory'))
|
|
16
|
+
throw new EngineError('PACKAGE_RESOURCE', `Missing package resource: ${directory}.`, 3);
|
|
17
|
+
return Object.fromEntries(walk(disk, root, directory).map((path) => [
|
|
18
|
+
path.slice(directory.length + 1),
|
|
19
|
+
disk.read(containedPath(root, path)),
|
|
20
|
+
]));
|
|
21
|
+
}
|
|
22
|
+
if (!inspect(disk, root, 'skills', 'directory'))
|
|
23
|
+
throw new EngineError('PACKAGE_RESOURCE', 'Package is missing its skills inventory.', 3);
|
|
24
|
+
const names = disk.names(containedPath(root, 'skills')).sort();
|
|
25
|
+
if (!names.length)
|
|
26
|
+
throw new EngineError('PACKAGE_RESOURCE', 'Package has no distributed skills.', 3);
|
|
27
|
+
return {
|
|
28
|
+
templates: { en: tree('templates/en'), 'pt-br': tree('templates/pt-br') },
|
|
29
|
+
skills: Object.fromEntries(names.map((name) => [name, tree(`skills/${name}`)])),
|
|
30
|
+
};
|
|
31
|
+
}
|
|
32
|
+
function read(io, root, path) {
|
|
33
|
+
if (!inspect(io, root, path, 'file'))
|
|
34
|
+
throw new EngineError('SOURCE_MISSING', `Missing source: ${path}. Run agentscli init to create missing setup.`, 2, path);
|
|
35
|
+
return io.read(containedPath(root, path));
|
|
36
|
+
}
|
|
37
|
+
function directoryPaths(files) {
|
|
38
|
+
const paths = new Set();
|
|
39
|
+
for (const file of files) {
|
|
40
|
+
const parts = file.split('/');
|
|
41
|
+
for (let index = 1; index < parts.length; index++)
|
|
42
|
+
paths.add(parts.slice(0, index).join('/'));
|
|
43
|
+
}
|
|
44
|
+
return paths;
|
|
45
|
+
}
|
|
46
|
+
function allDirectories(io, root, directory) {
|
|
47
|
+
if (!inspect(io, root, directory, 'directory'))
|
|
48
|
+
return [];
|
|
49
|
+
const result = [];
|
|
50
|
+
for (const name of io.names(containedPath(root, directory))) {
|
|
51
|
+
const path = `${directory}/${name}`;
|
|
52
|
+
if (inspect(io, root, path)?.kind === 'directory')
|
|
53
|
+
result.push(...allDirectories(io, root, path), path);
|
|
54
|
+
}
|
|
55
|
+
return result;
|
|
56
|
+
}
|
|
57
|
+
export function plan(io, root, command, resources, selectedLanguage) {
|
|
58
|
+
assertClientContext(io, root);
|
|
59
|
+
const initializing = command === 'init';
|
|
60
|
+
const manifest = initializing
|
|
61
|
+
? defaultManifest(selectedLanguage)
|
|
62
|
+
: parseManifest(decode(read(io, root, MANIFEST), MANIFEST));
|
|
63
|
+
inspect(io, root, manifest.templates_dir, 'directory');
|
|
64
|
+
inspect(io, root, manifest.conventions_dir, 'directory');
|
|
65
|
+
const effects = [];
|
|
66
|
+
function compare(path, content, preserve = false, force = false) {
|
|
67
|
+
const existing = inspect(io, root, path, 'file');
|
|
68
|
+
if (existing && preserve)
|
|
69
|
+
return;
|
|
70
|
+
const previous = existing ? io.read(containedPath(root, path)) : undefined;
|
|
71
|
+
if (!existing || force || !equalBytes(previous, content))
|
|
72
|
+
effects.push({
|
|
73
|
+
path,
|
|
74
|
+
action: existing ? 'update' : 'create',
|
|
75
|
+
content,
|
|
76
|
+
previous,
|
|
77
|
+
});
|
|
78
|
+
}
|
|
79
|
+
const virtual = new Map();
|
|
80
|
+
for (const path of walk(io, root, manifest.templates_dir))
|
|
81
|
+
if (path.endsWith('.tpl.md'))
|
|
82
|
+
virtual.set(path, read(io, root, path));
|
|
83
|
+
const main = `${manifest.templates_dir}/AGENTS.tpl.md`;
|
|
84
|
+
let initialized = virtual.has(main);
|
|
85
|
+
if (initializing && !initialized && inspect(io, root, MANIFEST, 'file')) {
|
|
86
|
+
const oldBytes = read(io, root, MANIFEST);
|
|
87
|
+
try {
|
|
88
|
+
parseManifest(decode(oldBytes, MANIFEST));
|
|
89
|
+
initialized = true;
|
|
90
|
+
}
|
|
91
|
+
catch (error) {
|
|
92
|
+
if (!(error instanceof EngineError))
|
|
93
|
+
throw error;
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
if (initializing) {
|
|
97
|
+
const defaults = resources.templates[manifest.language];
|
|
98
|
+
if (!defaults || !defaults['AGENTS.tpl.md'])
|
|
99
|
+
throw new EngineError('PACKAGE_RESOURCE', 'Package is missing its main template.', 3);
|
|
100
|
+
// Seed conventions before the main template: its presence must never hide
|
|
101
|
+
// defaults that a previous interrupted init has not created yet.
|
|
102
|
+
const defaultsInOrder = Object.entries(defaults).sort(([left], [right]) => left === 'AGENTS.tpl.md'
|
|
103
|
+
? 1
|
|
104
|
+
: right === 'AGENTS.tpl.md'
|
|
105
|
+
? -1
|
|
106
|
+
: left < right
|
|
107
|
+
? -1
|
|
108
|
+
: left > right
|
|
109
|
+
? 1
|
|
110
|
+
: 0);
|
|
111
|
+
for (const [relative, content] of defaultsInOrder) {
|
|
112
|
+
const path = `${manifest.templates_dir}/${relative}`;
|
|
113
|
+
if ((path === main || !initialized) && !virtual.has(path)) {
|
|
114
|
+
inspect(io, root, path, 'file');
|
|
115
|
+
virtual.set(path, content);
|
|
116
|
+
compare(path, content);
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
if (!virtual.has(main))
|
|
121
|
+
throw new EngineError('SOURCE_MISSING', `Missing main template: ${main}.`, 2, main);
|
|
122
|
+
const ordered = [...virtual.keys()].sort((a, b) => {
|
|
123
|
+
const left = portableKey(a), right = portableKey(b);
|
|
124
|
+
return left < right ? -1 : left > right ? 1 : 0;
|
|
125
|
+
});
|
|
126
|
+
uniquePaths(ordered);
|
|
127
|
+
const conventions = ordered
|
|
128
|
+
.filter((path) => path !== main)
|
|
129
|
+
.map((source) => ({
|
|
130
|
+
source,
|
|
131
|
+
output: `${manifest.conventions_dir}/${source.slice(manifest.templates_dir.length + 1, -7)}.md`,
|
|
132
|
+
text: decode(virtual.get(source), source),
|
|
133
|
+
}));
|
|
134
|
+
const documents = render({ source: main, text: decode(virtual.get(main), main) }, conventions, manifest.language);
|
|
135
|
+
uniquePaths([...documents.keys()]);
|
|
136
|
+
for (const [path, text] of documents) {
|
|
137
|
+
const existing = inspect(io, root, path, 'file');
|
|
138
|
+
if (existing && !isGenerated(io.read(containedPath(root, path))))
|
|
139
|
+
throw new EngineError('DOCUMENT_CONFLICT', `Manual document occupies ${path}. Preserve useful text in its template and resolve this destination before retrying.`, 2, path);
|
|
140
|
+
compare(path, bytes(text), initializing);
|
|
141
|
+
}
|
|
142
|
+
const stale = [];
|
|
143
|
+
if (!initializing)
|
|
144
|
+
for (const path of walk(io, root, manifest.conventions_dir)) {
|
|
145
|
+
if (path.endsWith('.md') &&
|
|
146
|
+
!documents.has(path) &&
|
|
147
|
+
isGenerated(io.read(containedPath(root, path))))
|
|
148
|
+
stale.push({
|
|
149
|
+
path,
|
|
150
|
+
action: 'delete',
|
|
151
|
+
previous: io.read(containedPath(root, path)),
|
|
152
|
+
});
|
|
153
|
+
}
|
|
154
|
+
const skillNames = Object.keys(resources.skills).sort();
|
|
155
|
+
if (!skillNames.length)
|
|
156
|
+
throw new EngineError('PACKAGE_RESOURCE', 'Package has no distributed skills.', 3);
|
|
157
|
+
for (const name of skillNames) {
|
|
158
|
+
if (!/^agentscli-[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(name))
|
|
159
|
+
throw new EngineError('PACKAGE_RESOURCE', `Invalid distributed skill name: ${name}.`, 3);
|
|
160
|
+
const skill = resources.skills[name];
|
|
161
|
+
if (!skill?.['SKILL.md'])
|
|
162
|
+
throw new EngineError('PACKAGE_RESOURCE', `Missing package skill: ${name}.`, 3);
|
|
163
|
+
uniquePaths(Object.keys(skill));
|
|
164
|
+
const directory = `.agents/skills/${name}`;
|
|
165
|
+
inspect(io, root, directory, 'directory');
|
|
166
|
+
const expected = new Set(Object.keys(skill).map((path) => `${directory}/${path}`));
|
|
167
|
+
for (const [relative, content] of Object.entries(skill))
|
|
168
|
+
compare(`${directory}/${relative}`, content, initializing);
|
|
169
|
+
if (!initializing) {
|
|
170
|
+
for (const path of walk(io, root, directory))
|
|
171
|
+
if (!expected.has(path))
|
|
172
|
+
stale.push({
|
|
173
|
+
path,
|
|
174
|
+
action: 'delete',
|
|
175
|
+
previous: io.read(containedPath(root, path)),
|
|
176
|
+
});
|
|
177
|
+
const expectedDirectories = directoryPaths([...expected]);
|
|
178
|
+
for (const path of allDirectories(io, root, directory))
|
|
179
|
+
if (!expectedDirectories.has(path))
|
|
180
|
+
stale.push({ path, action: 'delete', directory: true });
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
effects.push(...stale);
|
|
184
|
+
// Publish client configuration only after the complete setup. Retry can use
|
|
185
|
+
// the existing main template to distinguish completed setup from a fresh root.
|
|
186
|
+
if (initializing)
|
|
187
|
+
compare(MANIFEST, bytes(serializeManifest(manifest)), false, true);
|
|
188
|
+
uniquePaths(effects.filter((effect) => !effect.directory).map((effect) => effect.path));
|
|
189
|
+
return effects;
|
|
190
|
+
}
|
package/dist/render.js
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { GENERATED, validateConvention, validateTemplate } from './markdown.js';
|
|
2
|
+
function notice(source, language) {
|
|
3
|
+
const message = language === 'pt-br'
|
|
4
|
+
? `Arquivo gerado. Edite o template ${source}; alterações diretas serão sobrescritas.`
|
|
5
|
+
: `Generated file. Edit the template ${source}; direct changes will be overwritten.`;
|
|
6
|
+
return `${GENERATED}\n<!-- ${message} -->\n\n`;
|
|
7
|
+
}
|
|
8
|
+
function link(path) {
|
|
9
|
+
return path
|
|
10
|
+
.split('/')
|
|
11
|
+
.map((part) => encodeURIComponent(part).replace(/[()]/gu, (character) => character === '(' ? '%28' : '%29'))
|
|
12
|
+
.join('/');
|
|
13
|
+
}
|
|
14
|
+
export function render(main, conventions, language) {
|
|
15
|
+
const template = validateTemplate(main.text, main.source), outputs = new Map();
|
|
16
|
+
const entries = conventions.map((input) => {
|
|
17
|
+
const parsed = validateConvention(input.text, input.source);
|
|
18
|
+
outputs.set(input.output, notice(input.source, language) + parsed.body);
|
|
19
|
+
const title = parsed.title.replace(/[\\[\]]/gu, '\\$&');
|
|
20
|
+
return `- [${title}](${link(input.output)})\n${parsed.card
|
|
21
|
+
.split('\n')
|
|
22
|
+
.map((line) => ` ${line}`)
|
|
23
|
+
.join('\n')}`;
|
|
24
|
+
});
|
|
25
|
+
const lines = template.text.split('\n');
|
|
26
|
+
lines.splice(template.insertion, 1, entries.join('\n\n'));
|
|
27
|
+
outputs.set('AGENTS.md', notice(main.source, language) + lines.join('\n').trimEnd() + '\n');
|
|
28
|
+
return outputs;
|
|
29
|
+
}
|
package/dist/runtime.js
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
import { containedPath } from './paths.js';
|
|
2
|
+
import { EngineError } from './manifest.js';
|
|
3
|
+
import { checkRoot, assertClientContext, disk, inspect, removeFile, replaceFile, } from './io.js';
|
|
4
|
+
import { loadResources, plan } from './plan.js';
|
|
5
|
+
export async function execute(command, options, dependencies = {}) {
|
|
6
|
+
const result = {
|
|
7
|
+
schemaVersion: 1,
|
|
8
|
+
command,
|
|
9
|
+
ok: true,
|
|
10
|
+
changes: [],
|
|
11
|
+
diagnostics: [],
|
|
12
|
+
};
|
|
13
|
+
const io = dependencies.io ?? disk;
|
|
14
|
+
let effects = [];
|
|
15
|
+
let completed = 0;
|
|
16
|
+
let applying = false;
|
|
17
|
+
try {
|
|
18
|
+
const root = checkRoot(io, options.repoRoot);
|
|
19
|
+
assertClientContext(io, root);
|
|
20
|
+
effects = plan(io, root, command, dependencies.resources ?? loadResources(), options.language);
|
|
21
|
+
if (command === 'validate')
|
|
22
|
+
return { exitCode: 0, result };
|
|
23
|
+
result.changes = effects.map(({ path, action }) => ({
|
|
24
|
+
path,
|
|
25
|
+
action,
|
|
26
|
+
status: 'pending',
|
|
27
|
+
}));
|
|
28
|
+
if (options.dryRun || options.check) {
|
|
29
|
+
if (command === 'init' && options.dryRun)
|
|
30
|
+
result.diagnostics.push({
|
|
31
|
+
code: 'INIT_PRESERVED',
|
|
32
|
+
message: 'Existing valid templates, regular skill files, and marked outputs are preserved. Only missing setup is created; the client manifest is overwritten with the selected language and default roots.',
|
|
33
|
+
});
|
|
34
|
+
const exitCode = options.check && effects.length ? 1 : 0;
|
|
35
|
+
result.ok = exitCode === 0;
|
|
36
|
+
return { exitCode, result };
|
|
37
|
+
}
|
|
38
|
+
applying = true;
|
|
39
|
+
for (const effect of effects) {
|
|
40
|
+
if (effect.action === 'delete') {
|
|
41
|
+
if (effect.directory) {
|
|
42
|
+
if (inspect(io, root, effect.path, 'directory'))
|
|
43
|
+
io.rmdir(containedPath(root, effect.path));
|
|
44
|
+
}
|
|
45
|
+
else
|
|
46
|
+
removeFile(io, root, effect.path, effect.previous);
|
|
47
|
+
}
|
|
48
|
+
else
|
|
49
|
+
replaceFile(io, root, effect.path, effect.content, effect.previous);
|
|
50
|
+
result.changes[completed].status = 'completed';
|
|
51
|
+
completed++;
|
|
52
|
+
}
|
|
53
|
+
return { exitCode: 0, result };
|
|
54
|
+
}
|
|
55
|
+
catch (error) {
|
|
56
|
+
result.ok = false;
|
|
57
|
+
const known = error instanceof EngineError;
|
|
58
|
+
result.diagnostics.push({
|
|
59
|
+
code: known ? error.code : 'IO_FAILURE',
|
|
60
|
+
message: error instanceof Error ? error.message : 'File operation failed.',
|
|
61
|
+
...(known && error.path ? { path: error.path } : {}),
|
|
62
|
+
});
|
|
63
|
+
if (applying)
|
|
64
|
+
result.diagnostics.push({
|
|
65
|
+
code: 'RETRY_SYNC',
|
|
66
|
+
message: `${completed} of ${effects.length} effects completed. Fix the reported problem and ${command === 'init' ? 'repeat agentscli init with the same options to finish setup, then run agentscli sync' : 'run agentscli sync again to finish'}; no rollback was performed.`,
|
|
67
|
+
});
|
|
68
|
+
return { exitCode: applying ? 3 : known ? error.exitCode : 3, result };
|
|
69
|
+
}
|
|
70
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,46 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@devel-solid/agentscli",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "Generate project AGENTS.md and conventions from editable Markdown templates.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/devel-solid/agentscli.git"
|
|
9
|
+
},
|
|
10
|
+
"homepage": "https://github.com/devel-solid/agentscli#readme",
|
|
11
|
+
"bugs": "https://github.com/devel-solid/agentscli/issues",
|
|
12
|
+
"type": "module",
|
|
13
|
+
"bin": {
|
|
14
|
+
"agentscli": "dist/cli.js"
|
|
15
|
+
},
|
|
16
|
+
"files": [
|
|
17
|
+
"dist/**/*.js",
|
|
18
|
+
"dist/assets/"
|
|
19
|
+
],
|
|
20
|
+
"publishConfig": {
|
|
21
|
+
"access": "public"
|
|
22
|
+
},
|
|
23
|
+
"scripts": {
|
|
24
|
+
"build": "node scripts/clean-dist.mjs && tsc && node scripts/package-assets.mjs",
|
|
25
|
+
"typecheck": "tsc --noEmit",
|
|
26
|
+
"format": "prettier --write src scripts tests/unit package.json tsconfig.json .github/workflows/node.yml agentscli.yml",
|
|
27
|
+
"format:check": "prettier --check src scripts tests/unit package.json tsconfig.json .github/workflows/node.yml agentscli.yml",
|
|
28
|
+
"test": "tsc && node scripts/test.mjs",
|
|
29
|
+
"check": "npm run typecheck && npm run format:check && npm test",
|
|
30
|
+
"setup": "node scripts/setup.mjs",
|
|
31
|
+
"prepack": "npm run build"
|
|
32
|
+
},
|
|
33
|
+
"engines": {
|
|
34
|
+
"node": "^22.0.0 || ^24.0.0 || ^26.0.0"
|
|
35
|
+
},
|
|
36
|
+
"dependencies": {
|
|
37
|
+
"remark-parse": "11.0.0",
|
|
38
|
+
"unified": "11.0.5",
|
|
39
|
+
"yaml": "2.9.1"
|
|
40
|
+
},
|
|
41
|
+
"devDependencies": {
|
|
42
|
+
"@types/node": "22.20.5",
|
|
43
|
+
"prettier": "3.9.10",
|
|
44
|
+
"typescript": "7.0.2"
|
|
45
|
+
}
|
|
46
|
+
}
|