@devel-solid/agentscli 0.0.0-stage → 0.1.0

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 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,150 @@
1
- # Temporary Holding Version
1
+ # agentscli
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Generate a project's `AGENTS.md` and conventions from editable Markdown templates.
4
+ Package **@devel-solid/agentscli**, experimental version **0.1.0**, 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
+ # Project instructions
55
+
56
+ Keep project-wide orientation here.
57
+
58
+ <!-- agentscli:conventions -->
59
+ ~~~
60
+
61
+ Each convention template needs one H1 and one nonempty discovery card outside examples:
62
+
63
+ ~~~markdown
64
+ # Testing
65
+
66
+ <!-- AGENT-CARD START -->
67
+ Read when changing tests.
68
+ <!-- AGENT-CARD END -->
69
+
70
+ Keep tests focused on observable behavior.
71
+ ~~~
72
+
73
+ The card becomes part of the AGENTS index and is removed from the convention body.
74
+ Generated documents start with `<!-- agentscli:generated -->` and a source-edit notice.
75
+ `sync` replaces their entire content; put customizations in templates.
76
+
77
+ `validate` checks inputs, Markdown structure, paths, and destination conflicts.
78
+ `sync --dry-run` previews changes without writes. `sync --check` returns 1 for document
79
+ or managed-skill drift and 0 when current. Common options: `--repo-root <directory>`,
80
+ `--json`, `--help`; use `--version` by itself.
81
+
82
+ Unmarked documents occupying required output paths block all writes. Move useful
83
+ content into a template and resolve the destination before retrying. Other manual
84
+ documents remain untouched. Only stale marked Markdown below the **current**
85
+ conventions root is removed. Unsafe paths and file aliases are rejected.
86
+
87
+ Inputs and destinations are checked before writing. Files are replaced individually.
88
+ A failure can leave some documents or skills updated; diagnostics report completed
89
+ and remaining changes. Repeat `sync` to finish. Concurrent writes are unsupported.
90
+
91
+ JSON results contain `schemaVersion`, `command`, `ok`, `changes`, and `diagnostics`.
92
+ Exit codes: 0 success, 1 check drift, 2 usage/validation/conflict, 3 operational failure.
93
+
94
+ ## Skills
95
+
96
+ | Skill | This repository | Client project |
97
+ | --- | --- | --- |
98
+ | `agentscli-write-conventions` | Edit final conventions | Edit convention templates |
99
+ | `agentscli-update-agents` | Edit handwritten AGENTS | Edit the main template |
100
+ | `agentscli-build-agents` | — | Validate, preview, synchronize, check |
101
+ | `agentscli-release` | Native CLI versioning/publication | — |
102
+
103
+ Shared authoring skills select context using exactly one manifest:
104
+ `agentscli.yml` means direct repository authorship; `agentscli-compose.yml` means client
105
+ templates. Both or neither produces a diagnostic before edits. AGENTS stays concise;
106
+ detailed or scoped rules belong in conventions.
107
+
108
+ Client skills are installed under `.agents/skills`. **Sync fully restores the three
109
+ distributed directories**, including support files and removal of extra files.
110
+ Direct skill edits are overwritten. Other skills remain untouched. Previews and checks
111
+ include skill changes. The CLI also works without loading skills.
112
+
113
+ ## Develop and release
114
+
115
+ This repository keeps handwritten English AGENTS and conventions. It does not consume
116
+ itself: do not run client `init` or `sync` here. `agentscli.yml` only selects whole
117
+ skill directories for packaging and identifies direct authoring:
118
+
119
+ ~~~yaml
120
+ skills:
121
+ - .agents/skills/agentscli-write-conventions
122
+ - .agents/skills/agentscli-update-agents
123
+ - assets/templates/skills/agentscli-build-agents
124
+ ~~~
125
+
126
+ Shared skills have one source under `.agents/skills`; the client-only build skill lives
127
+ under `assets/templates/skills`. Build copies listed trees into `dist/assets/skills`
128
+ and both document locales into `dist/assets/templates`. Internal release/OpenSpec skills
129
+ and the internal manifest are excluded from the package.
130
+
131
+ ~~~sh
132
+ npm ci
133
+ npm run setup
134
+ npm run check
135
+ npm run build
136
+ npm pack --dry-run
137
+ npm pack --pack-destination .tmp
138
+ ~~~
139
+
140
+ `npm test` runs only lightweight unit tests with isolated data or mocked boundaries.
141
+ `check`, pre-push, and CI add type/format checks to that same unit gate. Build and
142
+ archive inspection are delivery checks. The package contains compiled runtime/client
143
+ resources, README, license, and metadata; installation performs no compilation or
144
+ resource download.
145
+
146
+ Use `agentscli-release` for native Git/npm versioning and publication. Review the source
147
+ commit, version/tag, archive contents, and integrity before delivery. Rename the existing
148
+ repository to `devel-solid/agentscli` preserving history. Commit, rename, tag, push, and
149
+ publish only within the corresponding authorization. Verify remote/registry identity
150
+ 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,40 @@
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
+ ## Preserve the format
27
+
28
+ In client mode, preserve valid UTF-8, exactly one H1, and exactly one full-line operational insertion comment outside examples:
29
+
30
+ ```markdown
31
+ <!-- agentscli:conventions -->
32
+ ```
33
+
34
+ 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.
35
+
36
+ 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.
37
+
38
+ 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.
39
+
40
+ 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,55 @@
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
+ ## Check the applicable format
36
+
37
+ Client templates require valid UTF-8, one H1, and exactly one complete, nonempty card outside code examples:
38
+
39
+ ```markdown
40
+ # Commit messages
41
+
42
+ <!-- AGENT-CARD START -->
43
+ Read when creating or reviewing a commit message.
44
+ <!-- AGENT-CARD END -->
45
+
46
+ Describe the concrete change in the commit subject.
47
+ ```
48
+
49
+ 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.
50
+
51
+ 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.
52
+
53
+ 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.
54
+
55
+ 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
+ # Project instructions
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
+ Customize this template with the project's purpose, important paths, and actual development commands. Keep detailed or task-specific rules in conventions.
8
+
9
+ ## Conventions
10
+
11
+ <!-- agentscli:conventions -->
@@ -0,0 +1,9 @@
1
+ # Project context
2
+
3
+ <!-- AGENT-CARD START -->
4
+ Read when starting work or choosing the project's development workflow.
5
+ <!-- AGENT-CARD END -->
6
+
7
+ Record the project's purpose, essential architecture, and verified development commands here. Replace this starting text with concrete instructions that apply to this project.
8
+
9
+ Keep unrelated changes outside the current request. Check existing conventions before adding another rule.
@@ -0,0 +1,11 @@
1
+ # Instruções do projeto
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
+ Personalize este template com o propósito do projeto, os caminhos importantes e os comandos de desenvolvimento reais. Mantenha regras detalhadas ou específicas de uma tarefa nas convenções.
8
+
9
+ ## Convenções
10
+
11
+ <!-- agentscli:conventions -->
@@ -0,0 +1,9 @@
1
+ # Contexto do projeto
2
+
3
+ <!-- AGENT-CARD START -->
4
+ Leia ao iniciar um trabalho ou escolher o fluxo de desenvolvimento do projeto.
5
+ <!-- AGENT-CARD END -->
6
+
7
+ Registre aqui o propósito do projeto, a arquitetura essencial e os comandos de desenvolvimento verificados. Substitua este texto inicial por instruções concretas que se apliquem a este projeto.
8
+
9
+ Mantenha alterações não relacionadas fora do pedido atual. Confira as convenções existentes antes de acrescentar outra regra.
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
+ }
@@ -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
+ }
@@ -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
+ }
@@ -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,48 @@
1
1
  {
2
2
  "name": "@devel-solid/agentscli",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
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 lefthook.yml agentscli.yml",
27
+ "format:check": "prettier --check src scripts tests/unit package.json tsconfig.json .github/workflows/node.yml lefthook.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
+ "lefthook:install": "lefthook install"
33
+ },
34
+ "engines": {
35
+ "node": "^22.0.0 || ^24.0.0 || ^26.0.0"
36
+ },
37
+ "dependencies": {
38
+ "remark-parse": "11.0.0",
39
+ "unified": "11.0.5",
40
+ "yaml": "2.9.1"
41
+ },
42
+ "devDependencies": {
43
+ "@types/node": "22.20.5",
44
+ "lefthook": "2.1.8",
45
+ "prettier": "3.9.10",
46
+ "typescript": "7.0.2"
47
+ }
48
+ }