drawbore 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/CHANGELOG.md ADDED
@@ -0,0 +1,29 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [0.1.1] - 2026-11-16
9
+
10
+ ### Fixed
11
+
12
+ - `drawbore init` with no flags now runs the interactive installer: checkbox prompts for harness locations, notebook creation, instruction files, and a final confirmation. The prompt layer existed in `lib/prompts.js` but was never wired into the CLI, so a bare `init` silently installed hardcoded defaults. Non-TTY streams (CI, pipes) still use the defaults without prompting.
13
+
14
+ ## [0.1.0] - 2026-11-16
15
+
16
+ Published to npm as `drawbore@0.1.0` (bootstrap publish; the first staged release is next).
17
+
18
+ ### Added
19
+
20
+ - Consent-aware installer for `.agents`, `.claude`, `.codex`, `.cursor`, `.omp`, and `.opencode`.
21
+ - `.drawbore/` notebook templates and a structural checker.
22
+ - `drawbore init` and `drawbore check` CLI commands.
23
+ - Seven portable skills: `discover`, `recall`, `frame`, `record`, `review`, `init-project`, and `release`.
24
+ - `init-project` generates a release pipeline from the project's answers — publish mode, build steps, and provider — instead of copying a template, and records the result in the root `AGENTS.md` under `publish mode` and `pipeline`.
25
+
26
+ ### Changed
27
+
28
+ - Skill conflicts are decided by content rather than by name. A skill directory is foreign only when its contents diverge from what the package ships; a file/directory mismatch is preserved instead of blocking the install.
29
+ - `release` branches on `publish mode` and `pipeline`, reading them from `AGENTS.md`. Sections written before those fields existed are still handled: the mode is inferred from the prose and the CI file, and the package field is read as either `package` or `npm package`.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Arthur Biazon Machado
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,76 @@
1
- # Temporary Holding Version
1
+ # Drawbore
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
+ [![GitLab pipeline](https://gitlab.com/abmach/drawbore/badges/main/pipeline.svg)](https://gitlab.com/abmach/drawbore/-/pipelines)
4
+
5
+ **You code. It holds.**
6
+
7
+ Durable context for AI-assisted software development.
8
+
9
+ Drawbore adds repository-aware context, engineering rules, and portable agent workflows on top of the repository and harness you already use. It adapts to the project rather than replacing the agent, the harness, or the repository’s own structure.
10
+
11
+ ## Status
12
+
13
+ The installer, notebook templates, structural checker, and portable skills are implemented.
14
+
15
+ ## What it provides
16
+
17
+ - **Durable context** — a `.drawbore/` containing purpose, scope, architecture, glossary, principles, decisions, current behavior, and technical choices.
18
+ - **Portable skills** — `discover`, `recall`, `frame`, `record`, `review`, `init-project`, and `release`.
19
+ - **Structural checks** — duplicate decision IDs, broken supersession, invalid records, missing headings, and stale-candidate warnings.
20
+ - **Consent-aware installation** — no file is overwritten without an explicit choice; locally modified skills are preserved.
21
+ - **Provider-neutral operation** — no forge, registry, or CI provider is assumed.
22
+
23
+ ## Install
24
+
25
+ ```sh
26
+ npx drawbore init
27
+ ```
28
+
29
+ The installer asks which harness locations should receive the skills, whether to create `.drawbore/`, and which instruction file should carry the Drawbore block. In non-interactive environments, use explicit flags:
30
+
31
+ ```sh
32
+ npx drawbore init --location .agents --notebook --instruction AGENTS.md --yes
33
+ ```
34
+
35
+ ### Supported locations
36
+
37
+ `.agents`, `.claude`, `.codex`, `.cursor`, `.omp`, `.opencode`
38
+
39
+ Each location receives its skills under `<location>/skills/`. The instruction file is selected from `AGENTS.md` or `CLAUDE.md`.
40
+
41
+ ## Check the notebook
42
+
43
+ ```sh
44
+ npx drawbore check
45
+ npx drawbore check --json
46
+ npx drawbore check --fix
47
+ ```
48
+
49
+ `check` is read-only unless `--fix` is passed. `--fix` only aligns decision IDs to filenames and renumbers duplicates; it never rewrites record bodies.
50
+
51
+ ## Skills
52
+
53
+ | Skill | Role |
54
+ |---|---|
55
+ | `discover` | Analyze an existing repository and propose its initial durable context |
56
+ | `recall` | Consult durable context before work and reconcile the implementation afterward |
57
+ | `frame` | Shape scope and maintain a Change Brief before implementation |
58
+ | `record` | Record confirmed terms, principles, decisions, behavior, and technical choices |
59
+ | `review` | Analyze a repository and propose a ranked plan, then implement only the approved items |
60
+ | `init-project` | Scaffold a provider-neutral project, including its release pipeline |
61
+ | `release` | Run a provider-neutral release flow |
62
+
63
+ ## Repository
64
+
65
+ This repository is canonical on GitLab. GitHub is a read-only distribution mirror: issues and releases live on GitLab.
66
+
67
+ ## Development
68
+
69
+ ```sh
70
+ npm install
71
+ npm test
72
+ ```
73
+
74
+ ## License
75
+
76
+ MIT
@@ -0,0 +1,335 @@
1
+ #!/usr/bin/env node
2
+
3
+ import path from "node:path";
4
+ import {
5
+ addInstruction,
6
+ buildInstructionChoices,
7
+ buildLocationChoices,
8
+ checkNotebook,
9
+ createNotebook,
10
+ createUi,
11
+ findProjectRoot,
12
+ fixMechanical,
13
+ inspectProject,
14
+ installMarkerFile,
15
+ installSkills,
16
+ loadPackageData,
17
+ notebookDirectory,
18
+ SkillConflictError,
19
+ summarize,
20
+ supportedLocations,
21
+ writeInstallMarker,
22
+ } from "../lib/index.js";
23
+
24
+ const CHECK_FLAGS = new Set(["--json", "--strict", "--fix"]);
25
+ const SUPPORTED_INSTRUCTIONS = new Set(["AGENTS.md", "CLAUDE.md"]);
26
+
27
+ const args = process.argv.slice(2);
28
+ const packageData = await loadPackageData();
29
+ const command = args[0];
30
+
31
+ if (args.includes("--help") || args.includes("-h")) {
32
+ if (command === "check") printCheckHelp(packageData.version);
33
+ else printHelp(packageData.version);
34
+ process.exit(0);
35
+ }
36
+
37
+ if (args.includes("--version") || args.includes("-v")) {
38
+ console.log(packageData.version);
39
+ process.exit(0);
40
+ }
41
+
42
+ if (command === "check") {
43
+ await runCheck(args.slice(1));
44
+ } else if (command !== "init") {
45
+ console.error("Usage: drawbore init | drawbore check");
46
+ process.exit(2);
47
+ } else {
48
+ let plan;
49
+ try {
50
+ plan = parseExplicitOptions(args.slice(1), packageData);
51
+ } catch (error) {
52
+ console.error(error.message);
53
+ printHelp(packageData.version);
54
+ process.exit(2);
55
+ }
56
+ const root = await findProjectRoot();
57
+ const inspection = await inspectProject(root);
58
+ const ui = createUi();
59
+
60
+ // No flags + non-interactive (pipe, CI, test): use the defaults rather than
61
+ // prompting on a stream nobody is reading. The prompts layer itself falls
62
+ // back to readline, which would block forever on a closed stdin.
63
+ if (!plan && !ui.isInteractive) {
64
+ plan = {
65
+ locations: [".agents"],
66
+ notebook: true,
67
+ instructions: [{ instructionFile: "AGENTS.md" }],
68
+ replaceSkills: false,
69
+ force: false,
70
+ skills: null,
71
+ };
72
+ }
73
+
74
+
75
+ try {
76
+ console.log(`Drawbore ${packageData.version}`);
77
+ console.log(`Project: ${root}`);
78
+
79
+ if (!plan) ui.renderProjectState(inspection);
80
+
81
+ const selectedLocations = plan?.locations ?? await pickLocations(inspection, ui);
82
+ if (selectedLocations.length === 0) {
83
+ console.log("No harness locations selected. Nothing was installed.");
84
+ process.exit(0);
85
+ }
86
+
87
+ const createNotebookDirectory = plan?.notebook ?? await pickNotebook(ui, inspection);
88
+ const instructionTargets = plan?.instructions ?? await pickInstructions(selectedLocations, inspection, ui);
89
+
90
+ if (!plan && !(await ui.confirm({ message: "Install Drawbore with these choices?", defaultValue: true }))) {
91
+ console.log("Installation cancelled. Nothing was installed.");
92
+ process.exit(0);
93
+ }
94
+
95
+ const selection = plan?.skills ? { ...packageData, skills: plan.skills } : packageData;
96
+ const preservedSkillFiles = [];
97
+ const replacedSkillFiles = [];
98
+ const skillHashes = {};
99
+
100
+ for (const location of selectedLocations) {
101
+ const result = await installSkills(root, location, selection, {
102
+ replaceExisting: plan?.replaceSkills === true,
103
+ force: plan?.force === true,
104
+ });
105
+ preservedSkillFiles.push(...result.preserved);
106
+ replacedSkillFiles.push(...result.replaced);
107
+ skillHashes[location] = result.hashes;
108
+ }
109
+
110
+ let notebookCreated = false;
111
+ if (createNotebookDirectory) {
112
+ await createNotebook(root);
113
+ notebookCreated = true;
114
+ }
115
+
116
+ const instructionFiles = [];
117
+ for (const target of instructionTargets) {
118
+ await addInstruction(root, target.instructionFile, packageData);
119
+ instructionFiles.push(target.instructionFile);
120
+ }
121
+
122
+ await writeInstallMarker(root, selection, selectedLocations, notebookCreated, [...new Set(instructionFiles)], skillHashes);
123
+ console.log(formatInstallResult(selectedLocations, notebookCreated, instructionFiles, preservedSkillFiles, replacedSkillFiles));
124
+ } catch (error) {
125
+ if (error instanceof SkillConflictError) {
126
+ console.error(error.message);
127
+ process.exit(1);
128
+ }
129
+ throw error;
130
+ } finally {
131
+ ui.close();
132
+ }
133
+ }
134
+
135
+ function parseExplicitOptions(options, packageData) {
136
+ if (options.length === 0) {
137
+ return undefined;
138
+ }
139
+
140
+ const locations = [];
141
+ const instructions = [];
142
+ let notebook = null;
143
+ let replaceSkills = false;
144
+ let force = false;
145
+ let skills = null;
146
+
147
+ for (let index = 0; index < options.length; index += 1) {
148
+ const option = options[index];
149
+ if (option === "--location") {
150
+ const value = options[++index];
151
+ if (value === undefined) throw new Error("Missing value for --location");
152
+ for (const location of splitList(value)) {
153
+ if (!supportedLocations[location]) throw new Error(`Unsupported location: ${location}`);
154
+ locations.push(location);
155
+ }
156
+ } else if (option === "--notebook") {
157
+ notebook = true;
158
+ } else if (option === "--instruction") {
159
+ const value = options[++index];
160
+ if (value === undefined) throw new Error("Missing value for --instruction");
161
+ for (const instructionFile of splitList(value)) {
162
+ if (!SUPPORTED_INSTRUCTIONS.has(instructionFile)) throw new Error(`Unsupported instruction file: ${instructionFile}`);
163
+ instructions.push({ instructionFile });
164
+ }
165
+ } else if (option === "--skills") {
166
+ const value = options[++index];
167
+ if (value === undefined) throw new Error("Missing value for --skills");
168
+ const requested = splitList(value);
169
+ const unknown = requested.filter((skill) => !packageData.skills.includes(skill));
170
+ if (unknown.length > 0) throw new Error(`Unknown skill(s): ${unknown.join(", ")}`);
171
+ skills = [...new Set(requested)];
172
+ } else if (option === "--replace-skills") {
173
+ replaceSkills = true;
174
+ } else if (option === "--force") {
175
+ force = true;
176
+ } else if (option === "--yes") {
177
+ // accepted for compatibility
178
+ } else {
179
+ throw new Error(`Unknown option: ${option}`);
180
+ }
181
+ }
182
+
183
+ if (locations.length === 0) locations.push(".agents");
184
+ if (notebook === null) notebook = true;
185
+ if (instructions.length === 0) {
186
+ for (const instructionFile of new Set(locations.map((location) => supportedLocations[location]))) {
187
+ instructions.push({ instructionFile });
188
+ }
189
+ }
190
+
191
+ return {
192
+ locations: [...new Set(locations)],
193
+ notebook,
194
+ replaceSkills,
195
+ force,
196
+ skills,
197
+ instructions: [...new Map(instructions.map((target) => [target.instructionFile, target])).values()],
198
+ };
199
+ }
200
+
201
+ async function pickLocations(inspection, ui) {
202
+ const choices = buildLocationChoices(inspection);
203
+ const selected = await ui.selectLocations(choices);
204
+ return validateSelectedLocations(selected);
205
+ }
206
+
207
+ async function pickNotebook(ui, inspection) {
208
+ const message = inspection.notebookExists
209
+ ? `Create or refresh the ${notebookDirectory} templates? Existing files will be preserved.`
210
+ : `Create ${notebookDirectory} with starter records?`;
211
+ return ui.confirm({ message, defaultValue: true });
212
+ }
213
+
214
+ async function pickInstructions(selectedLocations, inspection, ui) {
215
+ const targets = [...new Set(selectedLocations.map((location) => supportedLocations[location]))].map(
216
+ (instructionFile) => ({
217
+ instructionFile,
218
+ exists: inspection.locations.some((entry) => entry.instructionName === instructionFile && entry.instructionExists),
219
+ }),
220
+ );
221
+ const choices = buildInstructionChoices(targets);
222
+ const picked = await ui.selectInstructions(choices);
223
+
224
+ const invalid = picked.filter((value) => !targets.some((target) => target.instructionFile === value));
225
+ if (invalid.length > 0) {
226
+ throw new Error(`Unsupported instruction file(s): ${invalid.join(", ")}`);
227
+ }
228
+
229
+ return picked.map((instructionFile) => ({ instructionFile }));
230
+ }
231
+
232
+ function validateSelectedLocations(selected) {
233
+ if (!selected || selected.length === 0) {
234
+ return [];
235
+ }
236
+ const invalid = selected.filter((location) => !(location in supportedLocations));
237
+ if (invalid.length > 0) {
238
+ throw new Error(`Unsupported location(s): ${invalid.join(", ")}`);
239
+ }
240
+ return [...new Set(selected)];
241
+ }
242
+
243
+ function splitList(value) {
244
+ return value.split(",").map((item) => item.trim()).filter(Boolean);
245
+ }
246
+
247
+ async function runCheck(options) {
248
+ for (const option of options) {
249
+ if (!CHECK_FLAGS.has(option)) {
250
+ console.error(`Unknown option for check: ${option}`);
251
+ process.exit(2);
252
+ }
253
+ }
254
+
255
+ const json = options.includes("--json");
256
+ const strict = options.includes("--strict");
257
+ const fix = options.includes("--fix");
258
+ const root = await findProjectRoot();
259
+ const notebookDir = path.join(root, notebookDirectory);
260
+
261
+ if (fix) {
262
+ const { fixed } = await fixMechanical(notebookDir);
263
+ if (json) {
264
+ console.log(JSON.stringify({ fixed, changed: fixed.length > 0 }, null, 2));
265
+ } else if (fixed.length === 0) {
266
+ console.log("Nothing to fix.");
267
+ } else {
268
+ for (const item of fixed) {
269
+ console.log(`fixed ${item.code} ${item.file}: ${item.message}`);
270
+ }
271
+ }
272
+ }
273
+
274
+ const findings = await checkNotebook(notebookDir);
275
+ const summary = summarize(findings);
276
+
277
+ if (json) {
278
+ console.log(JSON.stringify({
279
+ ok: summary.ok,
280
+ errors: summary.errors,
281
+ warnings: summary.warnings,
282
+ stale: summary.stale,
283
+ }, null, 2));
284
+ } else if (findings.length === 0) {
285
+ console.log("No structural issues found.");
286
+ } else {
287
+ for (const finding of findings) {
288
+ const where = finding.file ? ` (${finding.file})` : "";
289
+ const tag = finding.code.startsWith("S") ? "review" : finding.code.startsWith("W") ? "warn" : "error";
290
+ console.log(`${finding.code} [${tag}]${where}: ${finding.message}`);
291
+ }
292
+ }
293
+
294
+ const failed = !summary.ok || (strict && summary.warnings.length > 0);
295
+ process.exit(failed ? 1 : 0);
296
+ }
297
+
298
+ function formatInstallResult(locations, notebookCreated, instructionFiles, preservedSkillFiles, replacedSkillFiles) {
299
+ const lines = ["", "Installed:"];
300
+ for (const location of locations) lines.push(`- skills: ${location}/skills/`);
301
+ if (notebookCreated) lines.push(`- record: ${notebookDirectory}/`);
302
+ for (const file of instructionFiles) lines.push(`- instruction: ${file}`);
303
+ lines.push(`- marker: ${installMarkerFile}`);
304
+ if (preservedSkillFiles.length > 0) lines.push("", `Preserved ${preservedSkillFiles.length} file(s).`);
305
+ if (replacedSkillFiles.length > 0) lines.push(`Replaced ${replacedSkillFiles.length} file(s).`);
306
+ lines.push("", "Run the discover skill in your agent to propose the first durable records.");
307
+ return lines.join("\n");
308
+ }
309
+
310
+ function printCheckHelp(version) {
311
+ console.log(`Drawbore ${version}\n\nUsage:\n drawbore check [--json] [--strict] [--fix]`);
312
+ }
313
+
314
+ function printHelp(version) {
315
+ console.log(`Drawbore ${version}
316
+
317
+ Usage:
318
+ drawbore init [options]
319
+ drawbore check [--json] [--strict] [--fix]
320
+ drawbore --version
321
+ drawbore --help
322
+
323
+ init options:
324
+ --location <dir> Harness location to install into (repeatable).
325
+ One of: .agents, .claude, .codex, .cursor, .omp, .opencode.
326
+ --notebook Create or refresh the .drawbore templates.
327
+ --instruction <file> Add the Drawbore block to an instruction file (repeatable).
328
+ One of: AGENTS.md, CLAUDE.md.
329
+ --skills <list> Comma-separated subset of skills to install.
330
+ --replace-skills Replace installed skill files that differ.
331
+ --force Replace skills owned by another package.
332
+ --yes Accept defaults without prompting.
333
+
334
+ Drawbore is provider-neutral: it does not assume a forge, registry, or CI provider.`);
335
+ }