@elvis1513/auto-coding-skill 5.0.5 → 5.2.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/README.md +53 -1
- package/cli/assets/managed-install.json +8 -4
- package/cli/assets/skill/SKILL.md +13 -20
- package/cli/assets/skill/data/templates/PROJECT.md +11 -27
- package/cli/assets/skill/data/templates/bridges/AGENTS.md +26 -64
- package/cli/assets/skill/references/parallel-development.md +39 -0
- package/cli/src/check-package.js +3 -2
- package/cli/src/diagnostics.js +121 -0
- package/cli/src/index.js +139 -8
- package/package.json +5 -3
- package/src/git-workflow/guard.py +451 -0
- package/src/git-workflow/test_guard.py +341 -0
package/cli/src/index.js
CHANGED
|
@@ -3,6 +3,7 @@ import crypto from "node:crypto";
|
|
|
3
3
|
import fs from "node:fs";
|
|
4
4
|
import path from "node:path";
|
|
5
5
|
import { fileURLToPath } from "node:url";
|
|
6
|
+
import { diagnostics } from "./diagnostics.js";
|
|
6
7
|
|
|
7
8
|
const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
|
|
8
9
|
const assetsRoot = path.join(packageRoot, "cli", "assets");
|
|
@@ -46,12 +47,15 @@ function copyTree(source, target) {
|
|
|
46
47
|
|
|
47
48
|
function parseArgs(argv) {
|
|
48
49
|
const [,, rawCommand, ...rest] = argv;
|
|
49
|
-
const args = { command: (!rawCommand || rawCommand === "-h" || rawCommand === "--help") ? "help" : rawCommand, dest: null, projects: [], json: false };
|
|
50
|
+
const args = { command: (!rawCommand || rawCommand === "-h" || rawCommand === "--help") ? "help" : rawCommand, dest: null, projects: [], json: false, dryRun: false, replaceManaged: false, backupDir: null };
|
|
50
51
|
for (let index = 0; index < rest.length; index += 1) {
|
|
51
52
|
const value = rest[index];
|
|
52
53
|
if (value === "--dest") args.dest = rest[++index] || fail("--dest requires a path");
|
|
53
54
|
else if (value === "--projects") args.projects.push(...(rest[++index] || fail("--projects requires paths")).split(",").filter(Boolean));
|
|
54
55
|
else if (value === "--json") args.json = true;
|
|
56
|
+
else if (value === "--dry-run") args.dryRun = true;
|
|
57
|
+
else if (value === "--replace-managed") args.replaceManaged = true;
|
|
58
|
+
else if (value === "--backup-dir") args.backupDir = rest[++index] || fail("--backup-dir requires a private external directory");
|
|
55
59
|
else if (value === "-h" || value === "--help") args.command = "help";
|
|
56
60
|
else if (value.startsWith("--")) fail(`unknown argument: ${value}`);
|
|
57
61
|
else args.projects.push(value);
|
|
@@ -59,6 +63,110 @@ function parseArgs(argv) {
|
|
|
59
63
|
return args;
|
|
60
64
|
}
|
|
61
65
|
|
|
66
|
+
function installSnapshot(root) {
|
|
67
|
+
const skill = managedTarget(root, ".agents/skills/auto-coding-skill");
|
|
68
|
+
const previous = readManifest(root);
|
|
69
|
+
const paths = new Set(["AGENTS.md", "docs/ENVIRONMENT.md", "docs/PROJECT.md", ".agents/managed-install.json"]);
|
|
70
|
+
if (skill && exists(skill)) {
|
|
71
|
+
if (!fs.statSync(skill).isDirectory()) fail("installed skill path is not a directory");
|
|
72
|
+
for (const file of listFiles(skill)) paths.add(`.agents/skills/auto-coding-skill/${file}`);
|
|
73
|
+
}
|
|
74
|
+
for (const entry of [...(Array.isArray(previous?.entries) ? previous.entries : []), ...(Array.isArray(previous?.legacy_entries) ? previous.legacy_entries : [])]) {
|
|
75
|
+
if (legacyManagedPath(entry?.path)) paths.add(entry.path);
|
|
76
|
+
}
|
|
77
|
+
return [...paths].sort().map(relative => {
|
|
78
|
+
const file = managedTarget(root, relative);
|
|
79
|
+
if (!file) fail(`unsafe install path: ${relative}`);
|
|
80
|
+
if (!exists(file)) return { path: relative, sha256: null };
|
|
81
|
+
if (!fs.statSync(file).isFile()) fail(`expected a regular file: ${relative}`);
|
|
82
|
+
return { path: relative, sha256: sha256(file) };
|
|
83
|
+
});
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
function installationPlan(project) {
|
|
87
|
+
const root = fs.realpathSync(path.resolve(project));
|
|
88
|
+
if (sourceRepository(root)) fail("this is the skill source repository; use npm run sync-assets and npm run release:check, not init/sync");
|
|
89
|
+
for (const relative of [".agents/skills/auto-coding-skill", ".agents/managed-install.json", "AGENTS.md", ...bootstrapDocs.map(([, target]) => target)]) {
|
|
90
|
+
if (!managedTarget(root, relative)) fail(`unsafe install path (symlink or invalid path): ${relative}`);
|
|
91
|
+
}
|
|
92
|
+
const snapshot = installSnapshot(root);
|
|
93
|
+
const expected = new Map(expectedEntries().map(entry => [entry.path, entry.sha256]));
|
|
94
|
+
const previous = readManifest(root);
|
|
95
|
+
const recorded = new Map();
|
|
96
|
+
for (const entry of Array.isArray(previous?.entries) ? previous.entries : []) {
|
|
97
|
+
if (!safeRelativePath(entry?.path) || !/^[a-f0-9]{64}$/.test(entry?.sha256)) continue;
|
|
98
|
+
recorded.set(entry.path, recorded.has(entry.path) ? null : entry.sha256);
|
|
99
|
+
}
|
|
100
|
+
const conflicts = [];
|
|
101
|
+
for (const entry of snapshot) {
|
|
102
|
+
if (!entry.sha256 || !(entry.path.startsWith(".agents/skills/auto-coding-skill/") || ["AGENTS.md", "docs/ENVIRONMENT.md"].includes(entry.path))) continue;
|
|
103
|
+
if (entry.sha256 === expected.get(entry.path) || entry.sha256 === recorded.get(entry.path)) continue;
|
|
104
|
+
// The existing legacy migration copies this complete document into a new PROJECT.md.
|
|
105
|
+
if (entry.path === "docs/ENVIRONMENT.md" && !isManaged(previous, entry.path) && !exists(path.join(root, "docs/PROJECT.md"))) continue;
|
|
106
|
+
conflicts.push({ path: entry.path, sha256: entry.sha256, reason: recorded.has(entry.path) ? "modified managed file" : "unowned file would be replaced" });
|
|
107
|
+
}
|
|
108
|
+
const current = new Map(snapshot.map(entry => [entry.path, entry.sha256]));
|
|
109
|
+
const changes = [...expected].filter(([relative, digest]) => current.get(relative) !== digest)
|
|
110
|
+
.map(([relative]) => ({ path: relative, action: current.get(relative) ? "refresh" : "install" }));
|
|
111
|
+
for (const entry of snapshot) if (entry.sha256 && entry.path.startsWith(".agents/skills/auto-coding-skill/") && !expected.has(entry.path)) changes.push({ path: entry.path, action: "retire" });
|
|
112
|
+
return { project: root, conflicts, changes, snapshot };
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
function assertUnchanged(plan) {
|
|
116
|
+
if (JSON.stringify(installSnapshot(plan.project)) !== JSON.stringify(plan.snapshot)) fail(`project changed during upgrade preparation; nothing further was refreshed: ${plan.project}`);
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
function backupConflicts(plans, directory) {
|
|
120
|
+
const requested = path.resolve(directory);
|
|
121
|
+
// Resolve even a not-yet-created suffix, so a symlinked parent cannot point into a project.
|
|
122
|
+
let ancestor = requested;
|
|
123
|
+
const suffix = [];
|
|
124
|
+
while (!exists(ancestor)) { suffix.unshift(path.basename(ancestor)); ancestor = path.dirname(ancestor); }
|
|
125
|
+
const resolved = path.join(fs.realpathSync(ancestor), ...suffix);
|
|
126
|
+
for (const plan of plans) {
|
|
127
|
+
const relative = path.relative(plan.project, resolved);
|
|
128
|
+
if (!relative || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative))) fail("backup directory must be outside every target project");
|
|
129
|
+
}
|
|
130
|
+
fs.mkdirSync(resolved, { recursive: true, mode: 0o700 });
|
|
131
|
+
const backup = fs.mkdtempSync(path.join(resolved, "autocoding-managed-"));
|
|
132
|
+
fs.chmodSync(backup, 0o700);
|
|
133
|
+
const records = [];
|
|
134
|
+
for (const plan of plans) {
|
|
135
|
+
assertUnchanged(plan);
|
|
136
|
+
const key = `${path.basename(plan.project)}-${crypto.createHash("sha256").update(plan.project).digest("hex").slice(0, 12)}`;
|
|
137
|
+
for (const conflict of plan.conflicts) {
|
|
138
|
+
const target = path.join(backup, key, conflict.path);
|
|
139
|
+
fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
|
|
140
|
+
fs.writeFileSync(target, fs.readFileSync(path.join(plan.project, conflict.path)), { flag: "wx", mode: 0o600 });
|
|
141
|
+
if (sha256(target) !== conflict.sha256) fail("managed file changed while backing up; no replacement was started");
|
|
142
|
+
records.push({ project: plan.project, ...conflict, backup_path: path.relative(backup, target) });
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
fs.writeFileSync(path.join(backup, "backup.json"), `${JSON.stringify({ version: pkg.version, files: records }, null, 2)}\n`, { flag: "wx", mode: 0o600 });
|
|
146
|
+
return backup;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
function installProjects(projects, args) {
|
|
150
|
+
if (args.replaceManaged && !args.backupDir) fail("--replace-managed requires --backup-dir outside the target projects; review and migrate project facts first");
|
|
151
|
+
if (args.backupDir && !args.replaceManaged) fail("--backup-dir requires --replace-managed");
|
|
152
|
+
const plans = [...new Set(projects.map(project => fs.realpathSync(path.resolve(project))))].map(installationPlan);
|
|
153
|
+
const conflicts = plans.some(plan => plan.conflicts.length > 0);
|
|
154
|
+
const preview = { version: pkg.version, dry_run: args.dryRun, can_apply: !conflicts || args.replaceManaged, results: plans.map(({ snapshot, ...plan }) => plan) };
|
|
155
|
+
if (args.dryRun || (conflicts && !args.replaceManaged)) {
|
|
156
|
+
toJson(preview, args.json);
|
|
157
|
+
if (conflicts && !args.replaceManaged) {
|
|
158
|
+
console.error("[autocoding] No files changed. Review the listed files, migrate useful facts to PROJECT.md/topic docs, then use --replace-managed --backup-dir <private-external-directory> if replacement is intended. No file contents or credentials are printed.");
|
|
159
|
+
process.exitCode = 1;
|
|
160
|
+
}
|
|
161
|
+
return;
|
|
162
|
+
}
|
|
163
|
+
const backup = conflicts ? backupConflicts(plans, args.backupDir) : null;
|
|
164
|
+
// Preflight the whole batch before the first installation, not one project at a time.
|
|
165
|
+
for (const plan of plans) assertUnchanged(plan);
|
|
166
|
+
const results = plans.map(plan => { assertUnchanged(plan); return { ...init(plan.project), backup }; });
|
|
167
|
+
toJson(args.command === "init" ? results[0] : { version: pkg.version, results }, args.json);
|
|
168
|
+
}
|
|
169
|
+
|
|
62
170
|
function readManifest(project) {
|
|
63
171
|
const file = managedTarget(project, ".agents/managed-install.json");
|
|
64
172
|
if (!file || !exists(file)) return null;
|
|
@@ -169,6 +277,10 @@ function init(project) {
|
|
|
169
277
|
for (const relative of [".agents/skills/auto-coding-skill", ".agents/managed-install.json", "AGENTS.md", ...bootstrapDocs.map(([, target]) => target)]) {
|
|
170
278
|
if (!managedTarget(root, relative)) fail(`unsafe install path (symlink or invalid path): ${relative}`);
|
|
171
279
|
}
|
|
280
|
+
// Topic scaffolding is bootstrap-only. A project may deliberately remove a
|
|
281
|
+
// placeholder or an entire empty topic; upgrades must honor that choice.
|
|
282
|
+
const established = Array.isArray(readManifest(root)?.project_documents)
|
|
283
|
+
&& exists(path.join(root, "docs/PROJECT.md"));
|
|
172
284
|
const { retired, retained } = retireExactLegacyFiles(root);
|
|
173
285
|
const installedSkill = path.join(root, ".agents", "skills", "auto-coding-skill");
|
|
174
286
|
fs.rmSync(installedSkill, { recursive: true, force: true });
|
|
@@ -181,6 +293,7 @@ function init(project) {
|
|
|
181
293
|
copyFile(source, path.join(root, targetRelative));
|
|
182
294
|
}
|
|
183
295
|
for (const [assetRelative, targetRelative] of projectDocs) {
|
|
296
|
+
if (established && targetRelative.endsWith("/.gitkeep")) continue;
|
|
184
297
|
const source = path.join(assetSkill, "data", "templates", assetRelative);
|
|
185
298
|
const target = path.join(root, targetRelative);
|
|
186
299
|
if (!exists(target)) {
|
|
@@ -292,27 +405,45 @@ function status(project) {
|
|
|
292
405
|
? listFiles(skill).map(file => `.agents/skills/auto-coding-skill/${file}`).filter(file => !expectedPaths.has(file)) : [];
|
|
293
406
|
currentErrors.push(...extra.map(file => `unexpected installed skill file: ${file}`));
|
|
294
407
|
const legacy = legacyFiles(root, manifest);
|
|
408
|
+
const assetsCurrent = currentErrors.length === 0;
|
|
295
409
|
currentErrors.push(...legacy.map(file => `legacy workflow file requires review: ${file}`));
|
|
296
410
|
const errors = [...integrityErrors, ...currentErrors];
|
|
297
411
|
const documents = Object.fromEntries(bootstrapDocs.map(([, target]) => [target, exists(path.join(root, target))]));
|
|
298
412
|
return { project: root, version: manifest?.skill_version || "", expected_version: pkg.version,
|
|
299
|
-
integrity: integrityErrors.length === 0, current: currentErrors.length === 0, ok: errors.length === 0,
|
|
413
|
+
integrity: integrityErrors.length === 0, assets_current: assetsCurrent, current: currentErrors.length === 0, ok: errors.length === 0,
|
|
300
414
|
errors, legacy_files: legacy, unexpected_files: extra, documents };
|
|
301
415
|
}
|
|
302
416
|
|
|
303
417
|
function help() {
|
|
304
|
-
console.log(`auto-coding-skill ${pkg.version}
|
|
418
|
+
console.log(`auto-coding-skill ${pkg.version}
|
|
419
|
+
|
|
420
|
+
autocoding init [--dest PATH] [--dry-run] [--json]
|
|
421
|
+
autocoding sync [--projects PATH[,PATH...]] [--dry-run] [--json]
|
|
422
|
+
autocoding status [--projects PATH[,PATH...]] [--json]
|
|
423
|
+
autocoding doctor [--projects PATH[,PATH...]] [--json]
|
|
424
|
+
autocoding guard-sync [--dest PATH] [--dry-run] [--json]
|
|
425
|
+
|
|
426
|
+
Changed or unowned managed files block replacement. Migrate project facts first,
|
|
427
|
+
then use --replace-managed --backup-dir <private-external-directory> if intended.
|
|
428
|
+
Doctor is read-only. Guard-sync only refreshes recognized Git guard source pairs;
|
|
429
|
+
it never opts a clone in, changes hooks, starts CI or deploys.`);
|
|
305
430
|
}
|
|
306
431
|
|
|
307
432
|
const args = parseArgs(process.argv);
|
|
433
|
+
const local = diagnostics({ packageRoot, managedTarget, sha256 });
|
|
308
434
|
if (args.command === "help") help();
|
|
309
|
-
else if (args.command === "init")
|
|
435
|
+
else if (args.command === "init") installProjects([args.dest || process.cwd()], args);
|
|
310
436
|
else if (args.command === "sync") {
|
|
311
437
|
const projects = args.projects.length ? args.projects : [process.cwd()];
|
|
312
|
-
|
|
313
|
-
} else if (args.command === "status") {
|
|
314
|
-
const projects = args.projects.length ? args.projects : [process.cwd()];
|
|
315
|
-
const results = projects.map(status);
|
|
438
|
+
installProjects(projects, args);
|
|
439
|
+
} else if (args.command === "status" || args.command === "doctor") {
|
|
440
|
+
const projects = args.projects.length ? args.projects : [args.dest || process.cwd()];
|
|
441
|
+
const results = projects.map(p => args.command === "doctor" ? local.doctor(status(p)) : status(p));
|
|
316
442
|
toJson({ version: pkg.version, results }, args.json);
|
|
317
443
|
if (results.some(result => !result.ok)) process.exitCode = 1;
|
|
444
|
+
} else if (args.command === "guard-sync") {
|
|
445
|
+
if (args.projects.length || args.replaceManaged || args.backupDir) fail("guard-sync accepts --dest PATH, --dry-run and --json only");
|
|
446
|
+
const result = local.guardSync(fs.realpathSync(args.dest || process.cwd()), args.dryRun);
|
|
447
|
+
toJson(result, args.json);
|
|
448
|
+
if (!result.ok) process.exitCode = 1;
|
|
318
449
|
} else fail(`unknown command: ${args.command}`);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@elvis1513/auto-coding-skill",
|
|
3
|
-
"version": "5.0
|
|
3
|
+
"version": "5.2.0",
|
|
4
4
|
"description": "Lightweight engineering guidance and a managed installer that preserves project-owned documentation.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
"cli/src",
|
|
11
11
|
"cli/assets/skill",
|
|
12
12
|
"cli/assets/managed-install.json",
|
|
13
|
+
"src/git-workflow/*.py",
|
|
13
14
|
"README.md",
|
|
14
15
|
"LICENSE"
|
|
15
16
|
],
|
|
@@ -17,11 +18,12 @@
|
|
|
17
18
|
"clean:cache": "find cli src -type d -name '__pycache__' -prune -exec rm -rf {} +",
|
|
18
19
|
"prepack": "npm run clean:cache",
|
|
19
20
|
"check:package": "npm run clean:cache && node cli/src/check-package.js",
|
|
20
|
-
"test": "node -c cli/src/index.js && node -c cli/src/sync-assets.js && node -c cli/tests/index.test.js && node cli/tests/index.test.js",
|
|
21
|
+
"test": "node -c cli/src/index.js && node -c cli/src/sync-assets.js && node -c cli/tests/index.test.js && node cli/tests/index.test.js && node cli/tests/parallel.test.js",
|
|
21
22
|
"test:src": "node -e \"const fs=require('fs'); for (const file of ['src/auto-coding-skill/SKILL.md','src/auto-coding-skill/data/templates/ENVIRONMENT.md','src/auto-coding-skill/data/templates/PROJECT.md','src/auto-coding-skill/data/templates/architecture/.gitkeep','src/auto-coding-skill/data/templates/product/.gitkeep','src/auto-coding-skill/data/templates/bridges/AGENTS.md']) if (!fs.existsSync(file)) throw new Error('missing '+file); console.log('source-doc-assets-ok')\"",
|
|
22
23
|
"check:assets": "node cli/src/sync-assets.js --check",
|
|
23
24
|
"sync-assets": "node cli/src/sync-assets.js",
|
|
24
|
-
"
|
|
25
|
+
"test:guard": "python3 -B src/git-workflow/test_guard.py -q",
|
|
26
|
+
"release:check": "npm run check:assets && npm run test:src && npm run test && npm run test:guard && npm run check:package"
|
|
25
27
|
},
|
|
26
28
|
"license": "MIT",
|
|
27
29
|
"publishConfig": {
|