@cassiomc1/forgeloop 2.0.0 → 2.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.
Files changed (49) hide show
  1. package/.cursor/rules/project-loop.mdc +1 -1
  2. package/.github/copilot-instructions.md +1 -1
  3. package/AGENTS.md +1 -1
  4. package/CLAUDE.md +1 -1
  5. package/ENG/design-code-eng.md +7 -5
  6. package/ENG/dotnet-aspnetcore-development-eng.md +8 -4
  7. package/ENG/nodejs-backend-development-eng.md +7 -4
  8. package/ENG/sql-development-eng.md +5 -4
  9. package/ENG/taste-frontend-eng.md +19 -5
  10. package/PROTOCOL_INTEGRATION.md +21 -0
  11. package/README.md +10 -7
  12. package/THIRD_PARTY_NOTICES.md +1 -0
  13. package/completions/_forgeloop +6 -1
  14. package/completions/forgeloop.bash +11 -1
  15. package/completions/forgeloop.fish +40 -1
  16. package/docs/AGENT_PROTOCOL_SUMMARY.md +6 -1
  17. package/docs/CLI_REFERENCE.md +88 -3
  18. package/docs/CODE_ATTESTATION.md +7 -0
  19. package/docs/FORGELOOP_AUDIT.md +1 -1
  20. package/docs/GETTING_STARTED.md +8 -1
  21. package/docs/PACKAGE_CONTENTS.md +4 -5
  22. package/docs/RELEASE_CHECKLIST.md +67 -13
  23. package/docs/STABLE_2_ACCEPTANCE.md +118 -71
  24. package/docs/TROUBLESHOOTING.md +167 -0
  25. package/package.json +1 -5
  26. package/src/cli.js +26 -0
  27. package/src/commands/assess.js +36 -0
  28. package/src/commands/evidence-export.js +17 -0
  29. package/src/commands/evidence-verify.js +36 -0
  30. package/src/commands/sync-pull.js +46 -0
  31. package/src/commands/sync-push.js +49 -0
  32. package/src/core/assessment/facts.js +146 -0
  33. package/src/core/assessment/plan.js +133 -0
  34. package/src/core/cli-command-definitions.js +70 -0
  35. package/src/core/command-executors.js +26 -3
  36. package/src/core/error-codes.js +232 -2
  37. package/src/core/evidence/bundle-format.js +72 -0
  38. package/src/core/evidence/export.js +179 -0
  39. package/src/core/evidence/markdown.js +40 -0
  40. package/src/core/evidence/verify.js +179 -0
  41. package/src/core/integration-invocation-policy.js +4 -2
  42. package/src/core/next-action-review-phase.js +14 -5
  43. package/src/core/parsers/dotnet-project.js +221 -0
  44. package/src/core/parsers/limits.js +9 -0
  45. package/src/core/parsers/pubspec.js +307 -0
  46. package/src/core/parsers/shared.js +4 -0
  47. package/src/core/project-detection.js +6 -527
  48. package/src/core/sync/remote.js +124 -0
  49. package/src/core/sync/snapshot.js +129 -0
@@ -0,0 +1,129 @@
1
+ import { createCipheriv, createDecipheriv, createHash, randomBytes, scryptSync } from "node:crypto";
2
+ import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
3
+ import path from "node:path";
4
+ import { gunzipSync, gzipSync } from "node:zlib";
5
+
6
+ // Cloud-sync snapshots: an attachment-inclusive storage backup directory,
7
+ // packed into JSON, gzipped and encrypted on the client with AES-256-GCM. The
8
+ // key is derived with scrypt from FORGELOOP_SYNC_KEY and never leaves this
9
+ // machine; the repository name is authenticated as associated data, so a
10
+ // snapshot cannot be replayed under another repository.
11
+
12
+ export const SNAPSHOT_KIND = "forgeloop-sync-snapshot";
13
+ export const MAX_SNAPSHOT_BYTES = 4 * 1024 * 1024;
14
+ export const MIN_PASSPHRASE_LENGTH = 16;
15
+ const SCRYPT = Object.freeze({ N: 1 << 15, r: 8, p: 1, maxmem: 64 * 1024 * 1024 });
16
+ const SAFE_SEGMENT = /^[A-Za-z0-9._-]+$/u;
17
+
18
+ export function syncError(code, message) {
19
+ return Object.assign(new Error(message), { code });
20
+ }
21
+
22
+ const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
23
+
24
+ // Relative POSIX paths only: no absolute paths, no "." or ".." segments.
25
+ export function isSafeSnapshotPath(value) {
26
+ if (typeof value !== "string" || value.length === 0 || value.length > 512) return false;
27
+ return value.split("/").every((segment) => SAFE_SEGMENT.test(segment) && segment !== "." && segment !== "..");
28
+ }
29
+
30
+ async function listFiles(root, relative = "") {
31
+ const entries = await readdir(path.join(root, relative), { withFileTypes: true });
32
+ const files = [];
33
+ for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
34
+ const child = relative ? `${relative}/${entry.name}` : entry.name;
35
+ if (entry.isDirectory()) files.push(...await listFiles(root, child));
36
+ else if (entry.isFile()) files.push(child);
37
+ else throw syncError("E_SYNC_SNAPSHOT_INVALID", `Backup contains an unsupported entry: ${child}`);
38
+ }
39
+ return files;
40
+ }
41
+
42
+ export async function packDirectory(directory) {
43
+ const files = [];
44
+ for (const name of await listFiles(directory)) {
45
+ if (!isSafeSnapshotPath(name)) throw syncError("E_SYNC_SNAPSHOT_INVALID", `Backup contains an unsafe path: ${name}`);
46
+ const bytes = await readFile(path.join(directory, name));
47
+ files.push({ path: name, sha256: sha256(bytes), data: bytes.toString("base64") });
48
+ }
49
+ return { schemaVersion: 1, files };
50
+ }
51
+
52
+ export async function unpackDirectory(payload, directory) {
53
+ if (!payload || payload.schemaVersion !== 1 || !Array.isArray(payload.files) || payload.files.length === 0) {
54
+ throw syncError("E_SYNC_SNAPSHOT_INVALID", "Snapshot payload has no files");
55
+ }
56
+ const seen = new Set();
57
+ for (const file of payload.files) {
58
+ if (!isSafeSnapshotPath(file?.path) || seen.has(file.path)) throw syncError("E_SYNC_SNAPSHOT_INVALID", "Snapshot payload has an unsafe or duplicate path");
59
+ seen.add(file.path);
60
+ const bytes = Buffer.from(String(file.data ?? ""), "base64");
61
+ if (sha256(bytes) !== file.sha256) throw syncError("E_SYNC_SNAPSHOT_INVALID", `Snapshot file digest mismatch: ${file.path}`);
62
+ const destination = path.join(directory, ...file.path.split("/"));
63
+ await mkdir(path.dirname(destination), { recursive: true });
64
+ await writeFile(destination, bytes, { flag: "wx" });
65
+ }
66
+ return [...seen];
67
+ }
68
+
69
+ function deriveKey(passphrase, salt) {
70
+ return scryptSync(passphrase, salt, 32, SCRYPT);
71
+ }
72
+
73
+ export function assertPassphrase(passphrase) {
74
+ if (typeof passphrase !== "string" || passphrase.length < MIN_PASSPHRASE_LENGTH) {
75
+ throw syncError("E_SYNC_CONFIG", `FORGELOOP_SYNC_KEY must be at least ${MIN_PASSPHRASE_LENGTH} characters`);
76
+ }
77
+ }
78
+
79
+ export function sealSnapshot(payload, { passphrase, repository, forgeloopVersion = null, now = new Date() }) {
80
+ assertPassphrase(passphrase);
81
+ const salt = randomBytes(16);
82
+ const iv = randomBytes(12);
83
+ const cipher = createCipheriv("aes-256-gcm", deriveKey(passphrase, salt), iv);
84
+ cipher.setAAD(Buffer.from(repository, "utf8"));
85
+ const data = Buffer.concat([cipher.update(gzipSync(Buffer.from(JSON.stringify(payload), "utf8"))), cipher.final()]);
86
+ const envelope = {
87
+ schemaVersion: 1,
88
+ kind: SNAPSHOT_KIND,
89
+ repository,
90
+ createdAt: now.toISOString(),
91
+ forgeloopVersion,
92
+ cipher: {
93
+ alg: "aes-256-gcm",
94
+ kdf: "scrypt",
95
+ kdfParams: { N: SCRYPT.N, r: SCRYPT.r, p: SCRYPT.p },
96
+ salt: salt.toString("base64"),
97
+ iv: iv.toString("base64"),
98
+ tag: cipher.getAuthTag().toString("base64"),
99
+ data: data.toString("base64"),
100
+ },
101
+ };
102
+ const body = Buffer.from(JSON.stringify(envelope), "utf8");
103
+ if (body.length > MAX_SNAPSHOT_BYTES) throw syncError("E_SYNC_TOO_LARGE", `Encrypted snapshot is ${body.length} bytes; the limit is ${MAX_SNAPSHOT_BYTES}`);
104
+ return body;
105
+ }
106
+
107
+ export function openSnapshot(body, { passphrase, repository }) {
108
+ assertPassphrase(passphrase);
109
+ let envelope;
110
+ try {
111
+ envelope = JSON.parse(Buffer.from(body).toString("utf8"));
112
+ } catch {
113
+ throw syncError("E_SYNC_SNAPSHOT_INVALID", "Remote snapshot is not valid JSON");
114
+ }
115
+ const cipher = envelope?.cipher;
116
+ if (envelope?.schemaVersion !== 1 || envelope.kind !== SNAPSHOT_KIND || cipher?.alg !== "aes-256-gcm" || cipher.kdf !== "scrypt") {
117
+ throw syncError("E_SYNC_SNAPSHOT_INVALID", "Remote snapshot has an unsupported format");
118
+ }
119
+ if (String(envelope.repository).toLowerCase() !== repository) throw syncError("E_SYNC_SNAPSHOT_INVALID", "Remote snapshot belongs to another repository");
120
+ try {
121
+ const decipher = createDecipheriv("aes-256-gcm", deriveKey(passphrase, Buffer.from(cipher.salt, "base64")), Buffer.from(cipher.iv, "base64"));
122
+ decipher.setAAD(Buffer.from(repository, "utf8"));
123
+ decipher.setAuthTag(Buffer.from(cipher.tag, "base64"));
124
+ const plain = Buffer.concat([decipher.update(Buffer.from(cipher.data, "base64")), decipher.final()]);
125
+ return { envelope, payload: JSON.parse(gunzipSync(plain).toString("utf8")) };
126
+ } catch {
127
+ throw syncError("E_SYNC_SNAPSHOT_INVALID", "Remote snapshot could not be decrypted: wrong FORGELOOP_SYNC_KEY or tampered data");
128
+ }
129
+ }