@cassiomc1/forgeloop 2.2.0 → 2.3.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 (58) hide show
  1. package/CONTRIBUTING.md +22 -2
  2. package/DOCS_INDEX.md +4 -13
  3. package/ENG/sec-code-eng.md +1 -1
  4. package/ENG/test-code-eng.md +32 -1
  5. package/LOOP_SYSTEM_DESIGN.md +2 -3
  6. package/QUALITY_SCORECARD.md +0 -1
  7. package/README.md +10 -42
  8. package/THIRD_PARTY_NOTICES.md +0 -15
  9. package/completions/_forgeloop +3 -2
  10. package/completions/forgeloop.bash +4 -2
  11. package/completions/forgeloop.fish +12 -1
  12. package/docs/AGENT_PROTOCOL_SUMMARY.md +3 -2
  13. package/docs/ARTIFACT_REFERENCE.md +1 -0
  14. package/docs/CLI_REFERENCE.md +24 -1
  15. package/docs/CODE_ATTESTATION.md +9 -7
  16. package/docs/DOCUMENTATION_GUIDE.md +10 -28
  17. package/docs/PACKAGE_CONTENTS.md +0 -3
  18. package/docs/RELEASE_CHECKLIST.md +52 -19
  19. package/docs/REVISION_PROVIDERS.md +3 -6
  20. package/docs/TROUBLESHOOTING.md +3 -0
  21. package/docs/documentation-manifest.json +0 -13
  22. package/package.json +2 -6
  23. package/schemas/config.schema.json +1 -0
  24. package/scripts/CI_VALIDATORS.md +2 -2
  25. package/src/cli.js +5 -0
  26. package/src/commands/attestation-create.js +21 -1
  27. package/src/commands/complete.js +3 -0
  28. package/src/commands/evidence-publish.js +22 -0
  29. package/src/commands/sync-pull.js +72 -7
  30. package/src/commands/sync-push.js +4 -1
  31. package/src/core/audit.js +7 -0
  32. package/src/core/cli-command-definitions.js +19 -1
  33. package/src/core/command-executors.js +19 -5
  34. package/src/core/config.js +44 -37
  35. package/src/core/error-codes.js +18 -0
  36. package/src/core/evidence/auto-export.js +61 -0
  37. package/src/core/evidence/bundle-format.js +4 -2
  38. package/src/core/evidence/export.js +5 -0
  39. package/src/core/evidence/publish.js +187 -0
  40. package/src/core/integration-invocation-policy.js +1 -0
  41. package/src/core/sync/merge.js +135 -0
  42. package/docs/assets/diagrams/forgeloop-code-attestation-flow.html +0 -13852
  43. package/docs/assets/diagrams/forgeloop-code-attestation-flow.receipt.json +0 -37
  44. package/docs/assets/diagrams/forgeloop-code-attestation-flow.svg +0 -5055
  45. package/docs/assets/diagrams/forgeloop-engineering-flow.html +0 -13837
  46. package/docs/assets/diagrams/forgeloop-engineering-flow.receipt.json +0 -37
  47. package/docs/assets/diagrams/forgeloop-engineering-flow.svg +0 -5011
  48. package/docs/assets/diagrams/forgeloop-verification-trust-flow.html +0 -13795
  49. package/docs/assets/diagrams/forgeloop-verification-trust-flow.receipt.json +0 -37
  50. package/docs/assets/diagrams/forgeloop-verification-trust-flow.svg +0 -4997
  51. package/docs/diagrams/README.md +0 -103
  52. package/docs/diagrams/forgeloop-code-attestation-flow.workflow.json +0 -451
  53. package/docs/diagrams/forgeloop-engineering-flow.workflow.json +0 -459
  54. package/docs/diagrams/forgeloop-verification-trust-flow.workflow.json +0 -398
  55. package/docs/diagrams/manifest.json +0 -84
  56. package/docs/diagrams/reviews/forgeloop-code-attestation-flow.review.json +0 -20
  57. package/docs/diagrams/reviews/forgeloop-engineering-flow.review.json +0 -20
  58. package/docs/diagrams/reviews/forgeloop-verification-trust-flow.review.json +0 -20
@@ -121,14 +121,18 @@ const runSearch = async (...args) => (await import("../commands/repository-index
121
121
  * The CLI renders these results; MCP and other integrations consume them
122
122
  * directly. No ownership, recovery, or lifecycle logic may live here.
123
123
  */
124
+ // Commands that write outside the project store (a backup destination, a
125
+ // user-config file) and therefore open the store read-only.
126
+ const READ_ONLY_STORAGE_COMMANDS = new Set(["storage-backup", "sync-push", "evidence-publish"]);
127
+
124
128
  const RAW_COMMAND_EXECUTORS = {
125
129
  "storage-restore-resume": async ({ target, packageRoot, options }) => {
126
130
  const { runStorageRestoreResume } = await import("../commands/storage-restore-resume.js");
127
- return { result: await runStorageRestoreResume({ target, packageRoot, operationId: options.operationId, expectedOwnerId: options.expectedOwnerId, writersQuiesced: options.writersQuiesced, replaceActive: options.replaceActive }), exitCode: 0 };
131
+ return { result: await runStorageRestoreResume({ target, packageRoot, operationId: options.operationId, expectedOwnerId: options.expectedOwnerId, writersQuiesced: options.writersQuiesced, replaceActive: options.replaceActive, merge: options.syncMerge, dryRun: options.dryRun }), exitCode: 0 };
128
132
  },
129
133
  "storage-restore": async ({ target, packageRoot, options }) => {
130
134
  const { runStorageRestore } = await import("../commands/storage-restore.js");
131
- return { result: await runStorageRestore({ target, packageRoot, source: options.source, writersQuiesced: options.writersQuiesced, replaceActive: options.replaceActive }), exitCode: 0 };
135
+ return { result: await runStorageRestore({ target, packageRoot, source: options.source, writersQuiesced: options.writersQuiesced, replaceActive: options.replaceActive, merge: options.syncMerge, dryRun: options.dryRun }), exitCode: 0 };
132
136
  },
133
137
  "storage-migration-status": async ({ target }) => {
134
138
  const { runStorageMigrationStatus } = await import("../commands/storage-migration-status.js");
@@ -156,7 +160,7 @@ const RAW_COMMAND_EXECUTORS = {
156
160
  },
157
161
  "sync-pull": async ({ target, packageRoot, options }) => {
158
162
  const { runSyncPull } = await import("../commands/sync-pull.js");
159
- return { result: await runSyncPull({ target, packageRoot, remote: options.syncRemote, repository: options.syncRepository, writersQuiesced: options.writersQuiesced, replaceActive: options.replaceActive }), exitCode: 0 };
163
+ return { result: await runSyncPull({ target, packageRoot, remote: options.syncRemote, repository: options.syncRepository, writersQuiesced: options.writersQuiesced, replaceActive: options.replaceActive, merge: options.syncMerge, dryRun: options.dryRun }), exitCode: 0 };
160
164
  },
161
165
  "storage-backup": async ({ target, options }) => {
162
166
  const { runStorageBackup } = await import("../commands/storage-backup.js");
@@ -431,6 +435,11 @@ const RAW_COMMAND_EXECUTORS = {
431
435
  result: await runEvidenceExport({ target, packageRoot, taskId: options.taskId, evidenceDirectory: options.evidenceDirectory }),
432
436
  exitCode: 0,
433
437
  }),
438
+ "evidence-publish": async ({ target, options }) => {
439
+ const { runEvidencePublish } = await import("../commands/evidence-publish.js");
440
+ const result = await runEvidencePublish({ target, taskId: options.taskId, all: options.all, evidenceDirectory: options.evidenceDirectory, remote: options.evidenceRemote, repository: options.evidenceRepository });
441
+ return { result, exitCode: result.status === "PUBLISHED" ? 0 : 1 };
442
+ },
434
443
  "evidence-verify": async ({ target, packageRoot, options }) => {
435
444
  const result = await runEvidenceVerify({ target, packageRoot, ...options });
436
445
  return { result, exitCode: exitCodeForAttestationResult(result) };
@@ -636,6 +645,10 @@ const RAW_COMMAND_EXECUTORS = {
636
645
  authorityContext,
637
646
  runtimeContext,
638
647
  });
648
+ if (result.status === "VALID") {
649
+ const { autoExportEvidence } = await import("./evidence/auto-export.js");
650
+ result.evidence = await autoExportEvidence({ target, packageRoot, taskId: options.taskId ?? null });
651
+ }
639
652
  return { result, exitCode: result.status === "VALID" ? 0 : 1 };
640
653
  },
641
654
  audit: async ({ target, packageRoot, options, authorityContext, runtimeContext }) => {
@@ -890,9 +903,10 @@ export const COMMAND_EXECUTORS = Object.fromEntries(Object.entries(RAW_COMMAND_E
890
903
  if (!context.target || name === "task-migrate" || name === "migrate-protocol" || name === "storage-migration-status" || name === "storage-rollback-resume" || name === "storage-rollback" || name === "storage-migrate" || name === "storage-migration-resume" || name === "storage-restore" || name === "storage-restore-resume" || name === "sync-pull") return executor(context);
891
904
  const { withProjectStorage } = await import("../storage/project-boundary.js");
892
905
  const { CLI_COMMAND_DEFINITIONS } = await import("./cli-command-definitions.js");
893
- // Backup (and sync-push, which backs up) writes its destination, not the source store. Doctor repairs only
906
+ // Backup (and sync-push, which backs up) writes its destination, not the source store, and
907
+ // evidence-publish writes only its user-config queue. Doctor repairs only
894
908
  // when explicitly requested; inspecting either must not migrate the source.
895
909
  const readOnly = CLI_COMMAND_DEFINITIONS[name]?.mutation === "READ_ONLY"
896
- || context.options?.dryRun === true || name === "storage-backup" || name === "sync-push" || (name === "doctor" && context.options?.fix !== true);
910
+ || context.options?.dryRun === true || READ_ONLY_STORAGE_COMMANDS.has(name) || (name === "doctor" && context.options?.fix !== true);
897
911
  return withProjectStorage(context.target, () => executor(context), { readOnly, runtimeContext: context.runtimeContext });
898
912
  }]));
@@ -25,48 +25,55 @@ function configurationError(message) {
25
25
  return error;
26
26
  }
27
27
 
28
+ function booleanOption(value, name) {
29
+ if (typeof value !== "boolean") throw configurationError(`${name} must be a boolean`);
30
+ return value;
31
+ }
32
+
33
+ function normalizeAttestationConfig(raw) {
34
+ if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
35
+ throw configurationError("attestation must be an object");
36
+ }
37
+ const mode = raw.mode ?? "optional";
38
+ if (!ATTESTATION_MODES.includes(mode)) throw configurationError(`Unknown attestation mode: ${mode}`);
39
+ const revisionProvider = raw.revisionProvider ?? "git";
40
+ if (typeof revisionProvider !== "string" || !revisionProvider.trim()) throw configurationError("attestation.revisionProvider must be a non-empty string");
41
+ const signing = raw.signing ?? {};
42
+ if (!signing || typeof signing !== "object" || Array.isArray(signing)) {
43
+ throw configurationError("attestation.signing must be an object");
44
+ }
45
+ const provider = signing.provider ?? "none";
46
+ if (!["none", "sigstore"].includes(provider)) throw configurationError(`Unknown attestation signing provider: ${provider}`);
47
+ const policy = signing.policy ?? {};
48
+ if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
49
+ throw configurationError("attestation.signing.policy must be an object");
50
+ }
51
+ if (policy.issuer !== undefined && typeof policy.issuer !== "string") throw configurationError("attestation.signing.policy.issuer must be a string");
52
+ if (policy.identities !== undefined) stringArray(policy.identities, "attestation.signing.policy.identities");
53
+ return {
54
+ mode,
55
+ revisionProvider,
56
+ requireCompleteCoverage: raw.requireCompleteCoverage === true,
57
+ ...(raw.autoExportEvidence !== undefined ? { autoExportEvidence: booleanOption(raw.autoExportEvidence, "attestation.autoExportEvidence") } : {}),
58
+ coverage: { exclude: stringArray(raw.coverage?.exclude ?? [], "attestation.coverage.exclude") },
59
+ signing: {
60
+ provider,
61
+ required: signing.required === true,
62
+ policy: {
63
+ ...(policy.issuer !== undefined ? { issuer: policy.issuer } : {}),
64
+ identities: [...(policy.identities ?? [])],
65
+ requireTransparencyLog: policy.requireTransparencyLog !== false,
66
+ },
67
+ },
68
+ };
69
+ }
70
+
28
71
  export function createConfig(input = {}) {
29
72
  const complianceMode = input.complianceMode ?? "standard";
30
73
  if (!COMPLIANCE_MODES.includes(complianceMode)) {
31
74
  throw configurationError(`Unknown compliance mode: ${complianceMode}`);
32
75
  }
33
- let attestation;
34
- if (input.attestation !== undefined) {
35
- if (!input.attestation || typeof input.attestation !== "object" || Array.isArray(input.attestation)) {
36
- throw configurationError("attestation must be an object");
37
- }
38
- const mode = input.attestation.mode ?? "optional";
39
- if (!ATTESTATION_MODES.includes(mode)) throw configurationError(`Unknown attestation mode: ${mode}`);
40
- const revisionProvider = input.attestation.revisionProvider ?? "git";
41
- if (typeof revisionProvider !== "string" || !revisionProvider.trim()) throw configurationError("attestation.revisionProvider must be a non-empty string");
42
- const signing = input.attestation.signing ?? {};
43
- if (!signing || typeof signing !== "object" || Array.isArray(signing)) {
44
- throw configurationError("attestation.signing must be an object");
45
- }
46
- const provider = signing.provider ?? "none";
47
- if (!["none", "sigstore"].includes(provider)) throw configurationError(`Unknown attestation signing provider: ${provider}`);
48
- const policy = signing.policy ?? {};
49
- if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
50
- throw configurationError("attestation.signing.policy must be an object");
51
- }
52
- if (policy.issuer !== undefined && typeof policy.issuer !== "string") throw configurationError("attestation.signing.policy.issuer must be a string");
53
- if (policy.identities !== undefined) stringArray(policy.identities, "attestation.signing.policy.identities");
54
- attestation = {
55
- mode,
56
- revisionProvider,
57
- requireCompleteCoverage: input.attestation.requireCompleteCoverage === true,
58
- coverage: { exclude: stringArray(input.attestation.coverage?.exclude ?? [], "attestation.coverage.exclude") },
59
- signing: {
60
- provider,
61
- required: signing.required === true,
62
- policy: {
63
- ...(policy.issuer !== undefined ? { issuer: policy.issuer } : {}),
64
- identities: [...(policy.identities ?? [])],
65
- requireTransparencyLog: policy.requireTransparencyLog !== false,
66
- },
67
- },
68
- };
69
- }
76
+ const attestation = input.attestation === undefined ? undefined : normalizeAttestationConfig(input.attestation);
70
77
  let verification;
71
78
  if (input.verification !== undefined) {
72
79
  try {
@@ -17,6 +17,9 @@ export const E_SYNC_CONFLICT = "E_SYNC_CONFLICT";
17
17
  export const E_SYNC_REMOTE = "E_SYNC_REMOTE";
18
18
  export const E_SYNC_SNAPSHOT_INVALID = "E_SYNC_SNAPSHOT_INVALID";
19
19
  export const E_SYNC_TOO_LARGE = "E_SYNC_TOO_LARGE";
20
+ export const E_SYNC_MERGE_CONFLICT = "E_SYNC_MERGE_CONFLICT";
21
+ export const E_EVIDENCE_PUBLISH_CONFIG = "E_EVIDENCE_PUBLISH_CONFIG";
22
+ export const E_EVIDENCE_PUBLISH_UNAUTHORIZED = "E_EVIDENCE_PUBLISH_UNAUTHORIZED";
20
23
  export const E_REPOSITORY_INDEX_PLATFORM_UNSUPPORTED = "E_REPOSITORY_INDEX_PLATFORM_UNSUPPORTED";
21
24
  export const E_REPOSITORY_INDEX_ENGINE_MISSING = "E_REPOSITORY_INDEX_ENGINE_MISSING";
22
25
  export const E_REPOSITORY_INDEX_ENGINE_DOWNLOAD_FAILED = "E_REPOSITORY_INDEX_ENGINE_DOWNLOAD_FAILED";
@@ -698,6 +701,18 @@ const CLOUD_SYNC_ERROR_METADATA = Object.freeze(Object.fromEntries([
698
701
  "The encrypted snapshot exceeds the 4 MiB sync limit.",
699
702
  "Sync a project with less retained state; cloud sync does not split snapshots.",
700
703
  ]],
704
+ [E_SYNC_MERGE_CONFLICT, [
705
+ "sync-pull --merge found tasks changed on both machines, or merged tasks would hold overlapping active claims, so nothing was changed.",
706
+ "Finish or abandon the task on one machine and sync it first, or run sync-pull --replace-active to adopt the remote state.",
707
+ ]],
708
+ [E_EVIDENCE_PUBLISH_CONFIG, [
709
+ "evidence-publish is missing FORGELOOP_SYNC_TOKEN, has nothing to publish, or --remote, --repo or a task ID is invalid.",
710
+ "Set FORGELOOP_SYNC_TOKEN, pass --task <id> or --all with an https --remote and an owner/name --repo (or a GitHub git origin).",
711
+ ]],
712
+ [E_EVIDENCE_PUBLISH_UNAUTHORIZED, [
713
+ "The evidence remote rejected FORGELOOP_SYNC_TOKEN, or the token is not allowed for this repository. The bundles stay queued.",
714
+ "Use a token issued for this repository, then run evidence-publish again to retry the queue.",
715
+ ]],
701
716
  ].map(([code, [meaning, safeResolution]]) => [code, Object.freeze({
702
717
  code,
703
718
  category: "cloud-sync",
@@ -1906,6 +1921,9 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
1906
1921
  E_SYNC_REMOTE,
1907
1922
  E_SYNC_SNAPSHOT_INVALID,
1908
1923
  E_SYNC_TOO_LARGE,
1924
+ E_SYNC_MERGE_CONFLICT,
1925
+ E_EVIDENCE_PUBLISH_CONFIG,
1926
+ E_EVIDENCE_PUBLISH_UNAUTHORIZED,
1909
1927
  E_REPOSITORY_INDEX_PLATFORM_UNSUPPORTED,
1910
1928
  E_REPOSITORY_INDEX_ENGINE_MISSING,
1911
1929
  E_REPOSITORY_INDEX_ENGINE_DOWNLOAD_FAILED,
@@ -0,0 +1,61 @@
1
+ import { readConfig } from "../config.js";
2
+ import { resolveSigningProvider } from "../signing/provider.js";
3
+ import { SIGNING_PROVIDERS } from "../signing/registry.js";
4
+ import { taskAttestationBundlePath, taskAttestationStatementPath } from "../task-paths.js";
5
+ import { withTaskTransaction } from "../transaction.js";
6
+ import { assertEvidenceTaskId } from "./bundle-format.js";
7
+ import { exportEvidenceBundle, hasAttestationSignature } from "./export.js";
8
+
9
+ // Signs the statement only when Sigstore is the configured provider and no
10
+ // signature exists yet: keyless signing publishes the signer identity, so it
11
+ // must follow explicit configuration and never replace an earlier signature.
12
+ async function signStatement({ target, packageRoot, taskId, signing, signer }) {
13
+ if (signing?.provider !== "sigstore") return { status: "NOT_CONFIGURED" };
14
+ try {
15
+ if (await hasAttestationSignature(target, taskId)) return { status: "EXISTING" };
16
+ const provider = signer ?? await resolveSigningProvider({ providerName: "sigstore", registry: SIGNING_PROVIDERS });
17
+ const result = await withTaskTransaction({ target, taskId, packageRoot, operation: "attestation-sign" }, () => provider.sign({
18
+ target,
19
+ statementPath: taskAttestationStatementPath(taskId),
20
+ bundlePath: taskAttestationBundlePath(taskId),
21
+ }));
22
+ if (result?.status === "VALID") return { status: "SIGNED" };
23
+ return { status: "FAILED", code: result?.code ?? "E_ATTESTATION_SIGNATURE_INVALID", message: result?.message ?? "Sigstore signing failed" };
24
+ } catch (error) {
25
+ return { status: "FAILED", code: error.code ?? "E_ATTESTATION_SIGNATURE_INVALID", message: error.message };
26
+ }
27
+ }
28
+
29
+ // Runs after a VALID completion has committed. Export is a convenience on top
30
+ // of the terminal state: every failure is reported, never thrown, so a broken
31
+ // export or signature cannot turn a valid completion into an error.
32
+ export async function autoExportEvidence({ target, packageRoot, taskId, signer = null } = {}) {
33
+ let attestation;
34
+ try {
35
+ attestation = (await readConfig(target, packageRoot))?.attestation ?? null;
36
+ } catch {
37
+ attestation = null;
38
+ }
39
+ if (attestation?.mode !== "required") return { status: "SKIPPED", reason: "attestation mode is not required" };
40
+ if (attestation.autoExportEvidence === false) return { status: "SKIPPED", reason: "attestation.autoExportEvidence is false" };
41
+ if (!taskId) return { status: "SKIPPED", reason: "complete ran without --task" };
42
+ try {
43
+ assertEvidenceTaskId(taskId);
44
+ } catch {
45
+ return { status: "SKIPPED", reason: "task ID cannot name an evidence bundle" };
46
+ }
47
+ try {
48
+ const { runAttestationCreate } = await import("../../commands/attestation-create.js");
49
+ await runAttestationCreate({ target, packageRoot, taskId });
50
+ const signature = await signStatement({ target, packageRoot, taskId, signing: attestation.signing, signer });
51
+ const exported = await exportEvidenceBundle({ target, packageRoot, taskId });
52
+ return { status: "EXPORTED", path: exported.path, digest: exported.digest, coveredPaths: exported.coveredPaths, signed: exported.signed, signature };
53
+ } catch (error) {
54
+ return {
55
+ status: "FAILED",
56
+ code: error.code ?? "E_EVIDENCE_EXPORT_UNAVAILABLE",
57
+ message: error.message,
58
+ next: `forgeloop attestation-create --task ${taskId} && forgeloop evidence-export --task ${taskId}`,
59
+ };
60
+ }
61
+ }
@@ -19,7 +19,9 @@ export const EVIDENCE_REDACTIONS = Object.freeze([
19
19
  "ledger-events",
20
20
  ]);
21
21
 
22
- const TASK_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/u;
22
+ // Task IDs may contain dots (release-2.2.0); a leading letter or digit and the
23
+ // absence of separators keep the bundle file name inside the evidence directory.
24
+ const TASK_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/u;
23
25
 
24
26
  export function evidenceError(code, message, details = {}) {
25
27
  return Object.assign(new Error(message), { code, ...details });
@@ -27,7 +29,7 @@ export function evidenceError(code, message, details = {}) {
27
29
 
28
30
  export function assertEvidenceTaskId(taskId) {
29
31
  if (typeof taskId !== "string" || !TASK_ID_PATTERN.test(taskId)) {
30
- throw evidenceError(E_EVIDENCE_BUNDLE_INVALID, `Invalid evidence task ID: ${taskId}`);
32
+ throw evidenceError(E_EVIDENCE_BUNDLE_INVALID, `Invalid evidence task ID: ${taskId} (bundles need letters, digits, ".", "_" or "-", starting with a letter or digit)`);
31
33
  }
32
34
  return taskId;
33
35
  }
@@ -42,6 +42,11 @@ async function readSignatureText(target, taskId) {
42
42
  }
43
43
  }
44
44
 
45
+ // True when a Sigstore bundle is already stored for the task's statement.
46
+ export async function hasAttestationSignature(target, taskId) {
47
+ return withProjectReadSnapshot(target, async () => (await readSignatureText(target, taskId)) !== null);
48
+ }
49
+
45
50
  async function readOptional(target, relativePath, schemaName, packageRoot) {
46
51
  try { return (await readJsonArtifact(target, relativePath, schemaName, packageRoot)).value; } catch { return null; }
47
52
  }
@@ -0,0 +1,187 @@
1
+ import { createHash } from "node:crypto";
2
+ import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
3
+ import os from "node:os";
4
+ import path from "node:path";
5
+
6
+ import {
7
+ E_EVIDENCE_PUBLISH_CONFIG,
8
+ E_EVIDENCE_PUBLISH_UNAUTHORIZED,
9
+ } from "../error-codes.js";
10
+ import { ensureWithin } from "../filesystem.js";
11
+ import { resolveRepository } from "../sync/remote.js";
12
+ import { DEFAULT_EVIDENCE_DIRECTORY, assertEvidenceTaskId, evidenceBundlePath, evidenceError, parseEvidenceBundle } from "./bundle-format.js";
13
+
14
+ // Opt-in evidence publishing for the team dashboard. Nothing leaves the
15
+ // machine unless `forgeloop evidence-publish` runs, and only bundles that
16
+ // evidence-export already redacted and that still match their digest are sent.
17
+ // Requested bundles enter an offline queue kept outside the repository; every
18
+ // run retries it, so a laptop that was offline publishes on its next run. The
19
+ // remote treats a repeated bundle as unchanged, which makes retries safe.
20
+
21
+ export const DEFAULT_EVIDENCE_REMOTE = "https://forgeloop.monster/api/evidence";
22
+ const REQUEST_TIMEOUT_MS = 60_000;
23
+
24
+ function publishError(code, message) {
25
+ return evidenceError(code, message);
26
+ }
27
+
28
+ export function resolvePublishRemote(value) {
29
+ let url;
30
+ try {
31
+ url = new URL(value || DEFAULT_EVIDENCE_REMOTE);
32
+ } catch {
33
+ throw publishError(E_EVIDENCE_PUBLISH_CONFIG, "--remote must be a URL");
34
+ }
35
+ const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
36
+ if (url.protocol !== "https:" && !(local && url.protocol === "http:")) throw publishError(E_EVIDENCE_PUBLISH_CONFIG, "--remote must use https (http is allowed only for localhost)");
37
+ if (url.username || url.password || url.search || url.hash) throw publishError(E_EVIDENCE_PUBLISH_CONFIG, "--remote must not contain credentials, a query or a fragment");
38
+ return url.toString();
39
+ }
40
+
41
+ export function readPublishToken(env = process.env) {
42
+ const bearer = env.FORGELOOP_SYNC_TOKEN ?? "";
43
+ if (!/^[A-Za-z0-9._~+/-]{32,512}$/u.test(bearer)) throw publishError(E_EVIDENCE_PUBLISH_CONFIG, "FORGELOOP_SYNC_TOKEN must be set to a ForgeLoop token for this repository");
44
+ return bearer;
45
+ }
46
+
47
+ function queueFile(target, env) {
48
+ const base = env.FORGELOOP_EVIDENCE_QUEUE_DIR
49
+ || (env.XDG_CONFIG_HOME ? path.join(env.XDG_CONFIG_HOME, "forgeloop", "evidence-queue") : path.join(os.homedir(), ".config", "forgeloop", "evidence-queue"));
50
+ const key = createHash("sha256").update(path.resolve(target)).digest("hex").slice(0, 32);
51
+ return path.join(base, `${key}.json`);
52
+ }
53
+
54
+ export async function readPublishQueue(target, { env = process.env } = {}) {
55
+ try {
56
+ const parsed = JSON.parse(await readFile(queueFile(target, env), "utf8"));
57
+ return Array.isArray(parsed?.items)
58
+ ? parsed.items.filter((item) => typeof item?.taskId === "string" && typeof item?.path === "string" && typeof item?.remote === "string" && typeof item?.repository === "string")
59
+ : [];
60
+ } catch {
61
+ return [];
62
+ }
63
+ }
64
+
65
+ async function writePublishQueue(target, items, { env }) {
66
+ const file = queueFile(target, env);
67
+ await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
68
+ const temporary = `${file}.${process.pid}.tmp`;
69
+ await writeFile(temporary, `${JSON.stringify({ schemaVersion: 1, items }, null, 2)}\n`, { mode: 0o600 });
70
+ await rename(temporary, file);
71
+ }
72
+
73
+ // Explicit task IDs must be valid; --all skips files whose names cannot be
74
+ // evidence bundles instead of aborting the run.
75
+ async function requestedItems(target, { taskIds, all, directory, remote, repository }) {
76
+ const names = new Set(taskIds.map((taskId) => assertEvidenceTaskId(taskId)));
77
+ const skipped = [];
78
+ if (all) {
79
+ let entries = [];
80
+ try { entries = await readdir(ensureWithin(target, directory)); } catch { entries = []; }
81
+ for (const entry of entries.filter((name) => name.endsWith(".json")).sort()) {
82
+ const taskId = entry.slice(0, -".json".length);
83
+ try { names.add(assertEvidenceTaskId(taskId)); } catch { skipped.push(entry); }
84
+ }
85
+ }
86
+ const items = [...names].sort().map((taskId) => ({ taskId, path: evidenceBundlePath(directory, taskId), remote, repository }));
87
+ return { items, skipped };
88
+ }
89
+
90
+ async function send({ remote, repository, bearer, text, fetchImpl }) {
91
+ const url = new URL(remote);
92
+ url.searchParams.set("repo", repository);
93
+ try {
94
+ return await fetchImpl(url.toString(), {
95
+ method: "PUT",
96
+ headers: { authorization: `Bearer ${bearer}`, accept: "application/json", "content-type": "application/json" },
97
+ body: text,
98
+ signal: globalThis.AbortSignal.timeout(REQUEST_TIMEOUT_MS),
99
+ });
100
+ } catch (error) {
101
+ return { networkError: error.message };
102
+ }
103
+ }
104
+
105
+ // Publishes one queued bundle. Returns the item's outcome and whether it stays
106
+ // in the queue.
107
+ async function publishItem(target, item, context) {
108
+ let text;
109
+ try {
110
+ text = await readFile(ensureWithin(target, item.path), "utf8");
111
+ } catch {
112
+ return { outcome: { taskId: item.taskId, status: "MISSING", message: `${item.path} no longer exists` }, keep: false };
113
+ }
114
+ let bundle;
115
+ try {
116
+ bundle = parseEvidenceBundle(text, item.taskId);
117
+ } catch (error) {
118
+ return { outcome: { taskId: item.taskId, status: "INVALID", code: error.code, message: error.message }, keep: false };
119
+ }
120
+ const response = await send({ ...context, text });
121
+ if (response.networkError) return { outcome: { taskId: item.taskId, digest: bundle.digest, status: "QUEUED", message: `Remote unreachable: ${response.networkError}` }, keep: true };
122
+ const detail = await response.json().catch(() => ({}));
123
+ if (response.ok) return { outcome: { taskId: item.taskId, digest: bundle.digest, status: detail?.status === "unchanged" ? "UNCHANGED" : "PUBLISHED" }, keep: false };
124
+ const message = typeof detail?.error === "string" ? detail.error : `HTTP ${response.status}`;
125
+ if (response.status === 401 || response.status === 403) return { outcome: { taskId: item.taskId, digest: bundle.digest, status: "UNAUTHORIZED", message }, keep: true, unauthorized: message };
126
+ if (response.status === 400 || response.status === 413) return { outcome: { taskId: item.taskId, digest: bundle.digest, status: "REJECTED", message }, keep: false };
127
+ return { outcome: { taskId: item.taskId, digest: bundle.digest, status: "QUEUED", message }, keep: true };
128
+ }
129
+
130
+ export async function publishEvidence({
131
+ target,
132
+ taskIds = [],
133
+ all = false,
134
+ directory = DEFAULT_EVIDENCE_DIRECTORY,
135
+ remote,
136
+ repository,
137
+ env = process.env,
138
+ fetchImpl = fetch,
139
+ } = {}) {
140
+ const resolvedRemote = resolvePublishRemote(remote);
141
+ const resolvedRepository = await resolveRepository(target, repository).catch((error) => {
142
+ throw publishError(E_EVIDENCE_PUBLISH_CONFIG, error.message);
143
+ });
144
+ const bearer = readPublishToken(env);
145
+ // Queued items stay bound to the remote and repository they were queued
146
+ // for; a run with other flags leaves them untouched.
147
+ const queue = await readPublishQueue(target, { env });
148
+ const matches = (item) => item.remote === resolvedRemote && item.repository === resolvedRepository;
149
+ const elsewhere = queue.filter((item) => !matches(item));
150
+ const queued = queue.filter(matches);
151
+ const { items: requested, skipped } = await requestedItems(target, { taskIds, all, directory, remote: resolvedRemote, repository: resolvedRepository });
152
+ if (queued.length === 0 && requested.length === 0) {
153
+ throw publishError(E_EVIDENCE_PUBLISH_CONFIG, "Nothing to publish: pass --task <id> or --all, or run again after a queued publish");
154
+ }
155
+ const pending = [...new Map([...queued, ...requested].map((item) => [item.taskId, item])).values()];
156
+ // Queue first, so an interrupted run still retries every requested bundle.
157
+ await writePublishQueue(target, [...elsewhere, ...pending], { env });
158
+ const context = { remote: resolvedRemote, repository: resolvedRepository, bearer, fetchImpl };
159
+ const results = [];
160
+ const remaining = [];
161
+ let unauthorized = null;
162
+ for (const item of pending) {
163
+ if (unauthorized) {
164
+ results.push({ taskId: item.taskId, status: "QUEUED", message: "Not attempted after the remote refused the token" });
165
+ remaining.push(item);
166
+ continue;
167
+ }
168
+ const { outcome, keep, unauthorized: refused } = await publishItem(target, item, context);
169
+ results.push(outcome);
170
+ if (keep) remaining.push(item);
171
+ if (refused) unauthorized = refused;
172
+ }
173
+ await writePublishQueue(target, [...elsewhere, ...remaining], { env });
174
+ if (unauthorized) {
175
+ throw Object.assign(publishError(E_EVIDENCE_PUBLISH_UNAUTHORIZED, `The evidence remote refused FORGELOOP_SYNC_TOKEN: ${unauthorized}`), { results, queued: remaining.length });
176
+ }
177
+ const complete = results.every((result) => result.status === "PUBLISHED" || result.status === "UNCHANGED");
178
+ return {
179
+ schemaVersion: 1,
180
+ status: complete ? "PUBLISHED" : remaining.length > 0 ? "QUEUED" : "INCOMPLETE",
181
+ remote: resolvedRemote,
182
+ repository: resolvedRepository,
183
+ results,
184
+ queued: remaining.length,
185
+ skipped,
186
+ };
187
+ }
@@ -78,6 +78,7 @@ const STATIC_RISK_CLASSES = Object.freeze({
78
78
  "storage-backup": INTEGRATION_RISK_CLASSES.MAINTENANCE,
79
79
  "storage-restore": INTEGRATION_RISK_CLASSES.MAINTENANCE,
80
80
  "sync-push": INTEGRATION_RISK_CLASSES.MAINTENANCE,
81
+ "evidence-publish": INTEGRATION_RISK_CLASSES.MAINTENANCE,
81
82
  "sync-pull": INTEGRATION_RISK_CLASSES.MAINTENANCE,
82
83
  "storage-restore-resume": INTEGRATION_RISK_CLASSES.MAINTENANCE,
83
84
  activate: INTEGRATION_RISK_CLASSES.MAINTENANCE,
@@ -0,0 +1,135 @@
1
+ import { createHash } from "node:crypto";
2
+ import { copyFile, mkdir } from "node:fs/promises";
3
+ import path from "node:path";
4
+
5
+ import { assertSafePath } from "../filesystem.js";
6
+ import { claimsOverlap } from "../task-scope.js";
7
+ import { backupProjectStorage, verifyProjectStorageBackup } from "../../storage/project-backup.js";
8
+ import { openStorageDatabase } from "../../storage/connection.js";
9
+ import { verifyAttachmentFile } from "../../storage/attachment-files.js";
10
+ import { syncError } from "./snapshot.js";
11
+
12
+ // Three-way, task-granular merge of two ForgeLoop states (this machine and the
13
+ // remote snapshot). Every table except storage_meta and sessions is keyed by
14
+ // task_id, and each task's ledger is its own hash chain, so a whole task can
15
+ // move between stores without rewriting any history. Tasks are compared by a
16
+ // digest of all their rows; the base is the digest recorded at the last push
17
+ // or pull. Nothing is ever resolved inside a task: a task changed on both
18
+ // sides is a conflict.
19
+
20
+ // Table, ordering key. The order is the insert order (tasks first, for the
21
+ // foreign keys).
22
+ export const TASK_TABLES = Object.freeze([
23
+ ["tasks", "task_id"],
24
+ ["claims", "task_id, claim_norm"],
25
+ ["events", "task_id, seq"],
26
+ ["actions", "task_id, action_id"],
27
+ ["approvals", "task_id, approval_id"],
28
+ ["executions", "task_id, execution_id"],
29
+ ["task_artifacts", "task_id, kind, artifact_id"],
30
+ ["attachment_references", "task_id, reference_id"],
31
+ ]);
32
+
33
+ function rowsOf(db, table, order, taskId, schema = "main") {
34
+ return db.prepare(`SELECT * FROM ${schema}.${table} WHERE task_id = ? ORDER BY ${order}`).all(taskId);
35
+ }
36
+
37
+ // One digest per task over every task-scoped row (attachment bytes are bound
38
+ // through attachment_references.sha256).
39
+ export function taskDigests(db, schema = "main") {
40
+ const digests = {};
41
+ for (const { task_id: taskId } of db.prepare(`SELECT task_id FROM ${schema}.tasks ORDER BY task_id`).all()) {
42
+ const hash = createHash("sha256");
43
+ for (const [table, order] of TASK_TABLES) {
44
+ hash.update(`${table}\n`);
45
+ for (const row of rowsOf(db, table, order, taskId, schema)) hash.update(`${JSON.stringify(row, Object.keys(row).sort())}\n`);
46
+ }
47
+ digests[taskId] = hash.digest("hex");
48
+ }
49
+ return digests;
50
+ }
51
+
52
+ export function readDatabaseDigests(databasePath) {
53
+ const db = openStorageDatabase(databasePath, { readOnly: true });
54
+ try { return taskDigests(db); } finally { db.close(); }
55
+ }
56
+
57
+ // local/remote/base: { taskId: digest }. base may be null (no recorded base).
58
+ export function classifyTasks({ local, remote, base = null }) {
59
+ const result = { take: [], keep: [], same: [], conflicts: [] };
60
+ for (const taskId of [...new Set([...Object.keys(local), ...Object.keys(remote)])].sort()) {
61
+ const mine = local[taskId] ?? null;
62
+ const theirs = remote[taskId] ?? null;
63
+ const known = base ? base[taskId] ?? null : undefined;
64
+ if (mine === theirs) result.same.push(taskId);
65
+ else if (theirs === null) result.keep.push({ taskId, reason: "local only" });
66
+ else if (mine === null) result.take.push({ taskId, reason: "remote only" });
67
+ else if (known !== undefined && mine === known) result.take.push({ taskId, reason: "changed remotely" });
68
+ else if (known !== undefined && theirs === known) result.keep.push({ taskId, reason: "changed locally" });
69
+ else result.conflicts.push({ taskId, reason: known === undefined ? "differs and no sync base is recorded" : "changed on both machines" });
70
+ }
71
+ return result;
72
+ }
73
+
74
+ function activeClaims(db, schema, taskIds, include) {
75
+ const rows = db.prepare(`SELECT task_id, claim_norm FROM ${schema}.claims WHERE reservation_state = 'ACTIVE' ORDER BY task_id, claim_norm`).all();
76
+ return rows.filter((row) => include === taskIds.has(row.task_id));
77
+ }
78
+
79
+ // A task taken from the remote must not hold an active claim that overlaps an
80
+ // active claim of a task that stays local.
81
+ function assertNoClaimOverlap(db, taken) {
82
+ const takenIds = new Set(taken);
83
+ const incoming = activeClaims(db, "remote", takenIds, true);
84
+ const staying = activeClaims(db, "main", takenIds, false);
85
+ const overlaps = [];
86
+ for (const left of incoming) {
87
+ for (const right of staying) {
88
+ if (claimsOverlap(left.claim_norm, right.claim_norm)) overlaps.push(`${left.task_id}:${left.claim_norm} ↔ ${right.task_id}:${right.claim_norm}`);
89
+ }
90
+ }
91
+ if (overlaps.length > 0) throw syncError("E_SYNC_MERGE_CONFLICT", `Merged tasks would hold overlapping active claims: ${overlaps.slice(0, 5).join(", ")}`);
92
+ }
93
+
94
+ // Builds a verified backup at `destination` holding the local state plus the
95
+ // remote's version of every task in `take`. `localBackup` is a writable copy of
96
+ // the local storage backup and doubles as the attachment root.
97
+ export async function buildMergedBackup({ localBackup, remoteBackup, take, destination }) {
98
+ const remoteDatabase = await assertSafePath(remoteBackup, "state.sqlite");
99
+ const db = openStorageDatabase(await assertSafePath(localBackup, "state.sqlite"), { allowSchemaUpgrade: false });
100
+ try {
101
+ db.prepare("ATTACH DATABASE ? AS remote").run(remoteDatabase);
102
+ assertNoClaimOverlap(db, take);
103
+ const attachments = [];
104
+ db.exec("BEGIN IMMEDIATE");
105
+ try {
106
+ for (const taskId of take) {
107
+ for (const [table] of [...TASK_TABLES].reverse()) db.prepare(`DELETE FROM main.${table} WHERE task_id = ?`).run(taskId);
108
+ for (const [table, order] of TASK_TABLES) {
109
+ db.prepare(`INSERT INTO main.${table} SELECT * FROM remote.${table} WHERE task_id = ? ORDER BY ${order}`).run(taskId);
110
+ }
111
+ db.prepare("INSERT OR IGNORE INTO main.sessions SELECT * FROM remote.sessions WHERE task_id = ?").run(taskId);
112
+ attachments.push(...rowsOf(db, "attachment_references", "task_id, reference_id", taskId, "remote"));
113
+ }
114
+ db.exec("COMMIT");
115
+ } catch (error) {
116
+ db.exec("ROLLBACK");
117
+ throw error;
118
+ }
119
+ db.prepare("DETACH DATABASE remote").run();
120
+ for (const row of attachments) {
121
+ const reference = { taskId: row.task_id, referenceId: row.reference_id, path: row.path, size: row.size, sha256: row.sha256 };
122
+ await verifyAttachmentFile(remoteBackup, reference);
123
+ const destinationFile = await assertSafePath(localBackup, row.path);
124
+ await mkdir(path.dirname(destinationFile), { recursive: true });
125
+ await copyFile(await assertSafePath(remoteBackup, row.path), destinationFile);
126
+ await verifyAttachmentFile(localBackup, reference);
127
+ }
128
+ db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
129
+ await backupProjectStorage(db, localBackup, destination);
130
+ } finally {
131
+ db.close();
132
+ }
133
+ await verifyProjectStorageBackup(destination);
134
+ return destination;
135
+ }