-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy path08_macro_registry_guide.html
More file actions
204 lines (200 loc) · 13.5 KB
/
08_macro_registry_guide.html
File metadata and controls
204 lines (200 loc) · 13.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Own Macro Registry Guide - ProtoML 1.4.2+build67</title>
<link rel="stylesheet" href="help.css">
</head>
<body>
<nav class="topnav">
<a href="../toc.html">Contents</a>
<span class="version">ProtoML 1.4.2+build67</span>
</nav>
<main class="page">
<h1>Own Macro Registry Guide</h1>
<p>This guide shows how to build and maintain your own local ProtoML macro registry, publish packs into it, and consume those packs from a project meeting file.</p>
<h2>What this workflow is for</h2>
<p>Use a custom macro registry when you want a reusable, curated macro catalog for one team, one company, or one document domain instead of copying macro files between repositories.</p>
<p>This guide is about macro package registries only. It is not about <code>protoparser register "<dir>"</code>, which creates governance and status reports for document collections.</p>
<h2>Where a company registry can live</h2>
<ul>
<li>a simple internal web server that serves <code>protoml.registry.json</code> and pack files over HTTP or HTTPS</li>
<li>a shared local path such as <code>Z:\protoml-registry</code> or <code>/mnt/protoml-registry</code></li>
<li>an intranet static host or normal artifact/file server</li>
</ul>
<p>You do not need a special registry backend. A company registry can be just static JSON plus files on a plain web server or network path.</p>
<h2>Choose the right trust path first</h2>
<ul>
<li>Use bundled <code>{{macro_dir}}</code> macros first when the shipped macro set already covers the need</li>
<li>Use a registry when you need reusable custom packs across multiple projects or teams</li>
<li>Use detached signatures plus a registry when your custom macros should resolve to <code>trusted</code></li>
<li>Use unsigned local macros only for exploratory work where <code>unknown</code> is acceptable</li>
</ul>
<h2>Create the registry</h2>
<pre><code>protoparser macro_install init_registry "./my-registry"</code></pre>
<p>This creates the local registry root and the <code>protoml.registry.json</code> index file.</p>
<h2>Create a pack inside the registry</h2>
<pre><code>protoparser macro_install init_pack "meeting-kit" "./my-registry"</code></pre>
<p>This gives you a pack folder with a <code>protoml-pack.json</code> manifest and a place for the pack's macro files.</p>
<h2>Add macros to the pack</h2>
<p>Place your custom macro files into the pack and describe the pack in its manifest. A simple macro could look like this:</p>
<pre><code>@new_macro
=name:decisionCard
=docs:
Renders a highlighted decision summary.
=template:
<div class="decision-card">
<strong>{{title}}</strong><br>
{{text}}
</div></code></pre>
<h2>Add the pack to the registry index</h2>
<pre><code>protoparser macro_install registry_add "./my-registry" "./my-registry/packs/meeting-kit"</code></pre>
<p>If the pack changes later, refresh the registry entry with:</p>
<pre><code>protoparser macro_install registry_update "./my-registry" "./my-registry/packs/meeting-kit"</code></pre>
<h2>Connect a project to your registry</h2>
<pre><code>protoparser macro_install init
protoparser macro_install add_registry "./my-registry"</code></pre>
<p>This prepares the project-local macro configuration and adds your registry as a source.</p>
<h2>Install or sync a pack from the registry</h2>
<pre><code>protoparser macro_install add_package "meeting-kit" 1.0.0
protoparser macro_install sync</code></pre>
<p>Or install in one step:</p>
<pre><code>protoparser macro_install install "meeting-kit" 1.0.0</code></pre>
<p>The project then receives the installed files in <code>.protoml/macro-packs/</code> and a generated <code>macros.index.pml</code>.</p>
<h2>Bind the registry macros into a meeting file</h2>
<pre><code>@macros_import ".protoml/macro-packs/macros.index.pml"
@protocol "Architecture Review - {{date}}"
@participants
=lead:Jane Doe,jdoe,jdoe@example.com
@meeting "Architecture Review"
# Decisions
@@macro=decisionCard:title=Storage;text=Use the replicated storage tier</code></pre>
<p>This is the meeting-side integration step: the generated macro index exposes the installed macros, and the meeting document uses them with <code>@@macro=...</code>.</p>
<h2>Manage installed packs in a project</h2>
<ul>
<li>List installed packs: <code>protoparser macro_install list</code></li>
<li>Inspect a pack: <code>protoparser macro_install info "meeting-kit"</code></li>
<li>Change the requested version: <code>protoparser macro_install update_package "meeting-kit" 1.1.0</code></li>
<li>Remove the package definition: <code>protoparser macro_install remove_package "meeting-kit"</code></li>
<li>Uninstall and remove a pack from the project: <code>protoparser macro_install remove "meeting-kit"</code></li>
</ul>
<h2>Manage the registry itself</h2>
<ul>
<li>Add a pack entry: <code>registry_add</code></li>
<li>Refresh a changed pack entry: <code>registry_update</code></li>
<li>Remove a pack entry: <code>protoparser macro_install registry_remove "./my-registry" "meeting-kit"</code></li>
</ul>
<p>Removing a pack from the registry index stops future resolution through that registry entry, but existing project installs may still keep local copies until updated or removed.</p>
<h2>Signing workflow for registry macros</h2>
<p>If you want a registry-delivered macro to become <code>trusted</code> in the ProtoML trust workflow, the macro file itself must be signed and the signing author must be listed in the registry <code>authors</code> section.</p>
<pre><code>protoparser sign macro "./my-registry/packs/meeting-kit/macros/meeting_kit_sample.pml" "./keys/alice-private.pem" "Alice" alice-main</code></pre>
<p>This creates a detached <code>*.sig.json</code> file next to the macro. The registry then needs a matching trusted author entry:</p>
<pre><code>{
"version": 1,
"name": "my-registry",
"authors": [
{
"name": "Alice",
"trust": "trusted",
"keys": [
{
"id": "alice-main",
"public_key": "-----BEGIN PUBLIC KEY----- ..."
}
]
}
],
"packages": []
}</code></pre>
<p>After that, consumers can run <code>verify</code> or <code>trust</code> with <code>-trustRegistry=...</code> and the macro can resolve to <code>trusted</code> if it has no hard risk flags such as JavaScript or external URLs.</p>
<h2>Registries can be split or combined</h2>
<p>A ProtoML registry does not have to do everything at once. A registry may publish:</p>
<ul>
<li>package entries in <code>packages</code> for install, sync, and search workflows</li>
<li>author trust entries in <code>authors</code> for trust, verify, and validate workflows</li>
<li>or both in one combined registry</li>
</ul>
<p>That means teams can keep macro delivery in one registry and trusted authors in another if that better matches their release and security process.</p>
<h2>Recommended trust-aware workflow</h2>
<ol>
<li>Start with bundled macros when possible</li>
<li>Create a custom pack only for the gaps</li>
<li>Sign the pack macros before treating them as production-ready</li>
<li>Publish the signing authors in the registry <code>authors</code> list</li>
<li>Install the pack into the project and check it with <code>trust</code>, <code>verify</code>, or <code>validate -trust=...</code></li>
<li>Review JavaScript and external URLs explicitly, even for signed registry macros</li>
</ol>
<h2>What about built-in macros?</h2>
<p>Bundled built-in macros can resolve to <code>trusted</code> without detached sidecars when they match the shipped built-in hash manifest and do not trigger hard risk flags.</p>
<p>If built-in macros should participate in the exact same author-signature workflow as external macros, they still need detached signatures and a matching trusted author entry in a documented trust registry. Extra or modified files in the built-in macro directory are not automatically trusted.</p>
<h2>Detached sidecar workflow without a registry</h2>
<p>Not every signed macro has to live inside a registry.</p>
<p>Author side:</p>
<ul>
<li>sign the standalone macro file with <code>protoparser sign macro ...</code></li>
<li>ship the macro together with its <code>*.sig.json</code> sidecar</li>
<li>ship the public key through a documented channel</li>
</ul>
<p>User side:</p>
<ul>
<li>keep the macro and sidecar together</li>
<li>run <code>protoparser verify macro ...</code></li>
<li>treat the result as cryptographic verification, not as automatic registry trust</li>
</ul>
<h2>Remote registries</h2>
<p>ProtoML can already use remote registry URLs for discovery, trust lookup, and explicit search. The remote workflow is intentionally simple: the registry is just a JSON document plus reachable pack files behind normal HTTP or HTTPS URLs.</p>
<h2>What the registry admin must do</h2>
<ol>
<li>Host a <code>protoml.registry.json</code> file on a stable HTTP or HTTPS URL</li>
<li>Publish each pack at a stable remote location and make sure the registry <code>source</code> and <code>manifest</code> paths point to reachable files</li>
<li>Keep package versions immutable once published whenever possible</li>
<li>Optionally publish an <code>authors</code> list with trusted or untrusted authors and public keys for trust verification</li>
<li>Document whether the registry is public, internal, reviewed, or experimental</li>
</ol>
<p>A minimal remote registry usually looks like a static website, GitHub Pages site, internal web server, or artifact host that serves JSON and pack files without any special server logic.</p>
<h2>What the user must do</h2>
<ol>
<li>Add the remote registry to the project with <code>protoparser macro_install add_registry "https://example.org/protoml.registry.json"</code> if it should be part of the project config</li>
<li>Search it explicitly with <code>protoparser macro_install search "meeting" "https://example.org/protoml.registry.json"</code> if it should only be queried ad hoc</li>
<li>Use repeatable <code>-trustRegistry=...</code> flags with <code>trust</code>, <code>verify</code>, or <code>validate -trust=...</code> when one or more registries should act as author trust sources</li>
<li>Review the registry owner and pack maintainers before treating the registry as trusted</li>
</ol>
<h2>Local company registry variant</h2>
<p>Some teams do not want HTTP hosting at all. In that case, the same registry can live in a shared directory or mounted network path.</p>
<pre><code>protoparser macro_install add_registry "Z:\protoml-registry"
protoparser macro_install add_registry "/mnt/protoml-registry"
protoparser validate "./governance/release-checklist.pml" -trust=strict -trustRegistry="Z:\protoml-registry"</code></pre>
<p>This works well for internal-only environments where a reviewed file share or NFS path is easier to operate than a hosted web endpoint.</p>
<h2>Operational notes</h2>
<ul>
<li>Remote registries are best for discovery and trust lookup first</li>
<li>For controlled environments, teams should still prefer a reviewed internal registry</li>
<li>If a remote registry changes frequently, consumers should pin versions in <code>protoml.macros.json</code></li>
<li>Trust classification still comes from risk flags, signatures, and author trust, not from the fact that a registry happens to be remote</li>
</ul>
<h2>Recommended maintenance flow</h2>
<ol>
<li>Create or edit macros inside a pack</li>
<li>Update the pack version when behavior meaningfully changes</li>
<li>Refresh the registry entry</li>
<li>Update consuming projects and run <code>sync</code></li>
<li>Render HTML and verify the macro output in a real document</li>
</ol>
<h2>Practical advice</h2>
<ul>
<li>Keep packs focused on one domain such as meetings, approvals, finance, or legal output</li>
<li>Prefer semantic macro names that still make sense outside the original project</li>
<li>Use a local registry first before introducing remote distribution</li>
<li>Inspect the generated project macro index after pack changes</li>
</ul>
<h2>Related guides</h2>
<ul>
<li><a href="04_macros_guide.html">Macros Guide</a></li>
<li><a href="03_cli_workflows.html">CLI Reference</a></li>
<li><a href="11_examples_cookbook.html">Examples Cookbook</a></li>
<li><a href="13_macro_security_trust_model.html">Macro Security And Trust Model</a></li>
<li><a href="15a_signed_governance_workflow.html">Signed Governance Workflow Tutorial</a></li>
</ul>
</main>
</body>
</html>