@holmes-lab/holmes-kit 0.39.0 → 0.40.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/CHANGELOG.md +344 -6
- package/README.md +54 -41
- package/dist/.build-id +1 -1
- package/dist/holmes/admission/core/admission-policy.d.ts +37 -0
- package/dist/holmes/admission/core/admission-policy.js +147 -0
- package/dist/holmes/admission/core/bounded-reader.d.ts +56 -0
- package/dist/holmes/admission/core/bounded-reader.js +135 -0
- package/dist/holmes/admission/core/change-classifier.d.ts +34 -0
- package/dist/holmes/admission/core/change-classifier.js +278 -0
- package/dist/holmes/admission/core/config-loader.d.ts +30 -0
- package/dist/holmes/admission/core/config-loader.js +145 -0
- package/dist/holmes/admission/core/event-judgement.d.ts +37 -0
- package/dist/holmes/admission/core/event-judgement.js +251 -0
- package/dist/holmes/admission/core/path-rules.d.ts +35 -0
- package/dist/holmes/admission/core/path-rules.js +88 -0
- package/dist/holmes/admission/core/pin.d.ts +7 -0
- package/dist/holmes/admission/core/pin.js +29 -0
- package/dist/holmes/admission/core/ports.d.ts +48 -0
- package/dist/holmes/admission/core/ports.js +11 -0
- package/dist/holmes/admission/core/range-resolver.d.ts +32 -0
- package/dist/holmes/admission/core/range-resolver.js +51 -0
- package/dist/holmes/admission/core/self-containment.d.ts +1 -0
- package/dist/holmes/admission/core/self-containment.js +125 -0
- package/dist/holmes/admission/core/signature-source.d.ts +9 -0
- package/dist/holmes/admission/core/signature-source.js +4 -0
- package/dist/holmes/admission/core/transition-planner.d.ts +15 -0
- package/dist/holmes/admission/core/transition-planner.js +14 -0
- package/dist/holmes/admission/core/verdict.d.ts +38 -0
- package/dist/holmes/admission/core/verdict.js +17 -0
- package/dist/holmes/admission/core/wiring.d.ts +44 -0
- package/dist/holmes/admission/core/wiring.js +618 -0
- package/dist/holmes/admission/forge/git-object-port.d.ts +4 -0
- package/dist/holmes/admission/forge/git-object-port.js +132 -0
- package/dist/holmes/assoc/assoc-arm.d.ts +1 -1
- package/dist/holmes/assoc/assoc-arm.js +1 -1
- package/dist/holmes/cli/agents.d.ts +8 -0
- package/dist/holmes/cli/agents.js +9 -5
- package/dist/holmes/cli/approve-cli.d.ts +2 -0
- package/dist/holmes/cli/approve-cli.js +392 -0
- package/dist/holmes/cli/approve-ref.d.ts +13 -7
- package/dist/holmes/cli/approve-ref.js +30 -10
- package/dist/holmes/cli/approve-status.d.ts +26 -2
- package/dist/holmes/cli/approve-status.js +98 -18
- package/dist/holmes/cli/approve-watch.d.ts +5 -0
- package/dist/holmes/cli/approve-watch.js +10 -5
- package/dist/holmes/cli/approve.d.ts +49 -13
- package/dist/holmes/cli/approve.js +249 -67
- package/dist/holmes/cli/attest.js +2 -1
- package/dist/holmes/cli/autonomy.d.ts +4 -1
- package/dist/holmes/cli/autonomy.js +17 -10
- package/dist/holmes/cli/codex-oracle.d.ts +11 -0
- package/dist/holmes/cli/codex-oracle.js +5 -1
- package/dist/holmes/cli/codex-toml.d.ts +10 -0
- package/dist/holmes/cli/codex-toml.js +36 -2
- package/dist/holmes/cli/doctor-boundary.d.ts +76 -0
- package/dist/holmes/cli/doctor-boundary.js +308 -0
- package/dist/holmes/cli/doctor-locks.d.ts +15 -0
- package/dist/holmes/cli/doctor-locks.js +119 -0
- package/dist/holmes/cli/doctor.d.ts +2 -0
- package/dist/holmes/cli/doctor.js +34 -5
- package/dist/holmes/cli/flags.d.ts +23 -0
- package/dist/holmes/cli/flags.js +89 -0
- package/dist/holmes/cli/index.d.ts +5 -1
- package/dist/holmes/cli/index.js +202 -424
- package/dist/holmes/cli/init.js +33 -0
- package/dist/holmes/cli/lock-recover.d.ts +5 -0
- package/dist/holmes/cli/lock-recover.js +126 -0
- package/dist/holmes/cli/mcp-processes.js +1 -1
- package/dist/holmes/cli/release-docs.js +1 -1
- package/dist/holmes/cli/run-exec.d.ts +141 -0
- package/dist/holmes/cli/run-exec.js +1435 -0
- package/dist/holmes/cli/run-provision.d.ts +3 -1
- package/dist/holmes/cli/run-provision.js +255 -44
- package/dist/holmes/cli/run-wiring.d.ts +69 -0
- package/dist/holmes/cli/run-wiring.js +270 -0
- package/dist/holmes/cli/run.d.ts +21 -0
- package/dist/holmes/cli/run.js +341 -92
- package/dist/holmes/cli/runtime-binding-approval.js +32 -19
- package/dist/holmes/cli/screen-safe.d.ts +3 -92
- package/dist/holmes/cli/screen-safe.js +18 -756
- package/dist/holmes/config/config.d.ts +2 -0
- package/dist/holmes/config/config.js +5 -2
- package/dist/holmes/cpg/foundation/language-matrix.js +2 -2
- package/dist/holmes/cpg/import-resolver.js +1 -1
- package/dist/holmes/governance/approval-decisions.d.ts +47 -0
- package/dist/holmes/governance/approval-decisions.js +29 -0
- package/dist/holmes/governance/approval-grants.d.ts +220 -1
- package/dist/holmes/governance/approval-grants.js +612 -33
- package/dist/holmes/governance/approval-queue.d.ts +26 -0
- package/dist/holmes/governance/approval-queue.js +109 -11
- package/dist/holmes/governance/approval-spend.d.ts +95 -0
- package/dist/holmes/governance/approval-spend.js +191 -0
- package/dist/holmes/governance/autonomous-shell.d.ts +61 -0
- package/dist/holmes/governance/autonomous-shell.js +332 -0
- package/dist/holmes/governance/autonomy.d.ts +5 -0
- package/dist/holmes/governance/autonomy.js +16 -11
- package/dist/holmes/governance/constitution.d.ts +5 -0
- package/dist/holmes/governance/constitution.js +32 -12
- package/dist/holmes/governance/full-autonomy.d.ts +10 -0
- package/dist/holmes/governance/full-autonomy.js +103 -7
- package/dist/holmes/governance/harness-catalog.d.ts +103 -0
- package/dist/holmes/governance/harness-catalog.js +348 -0
- package/dist/holmes/governance/human-channel.d.ts +38 -0
- package/dist/holmes/governance/human-channel.js +49 -0
- package/dist/holmes/governance/install-manifest.d.ts +22 -0
- package/dist/holmes/governance/install-manifest.js +160 -0
- package/dist/holmes/governance/ledger-rechain.js +2 -0
- package/dist/holmes/governance/ledger-store.conformance.d.ts +7 -1
- package/dist/holmes/governance/ledger-store.conformance.js +66 -0
- package/dist/holmes/governance/ledger-store.d.ts +88 -11
- package/dist/holmes/governance/ledger-store.js +186 -8
- package/dist/holmes/governance/provenance-chain.d.ts +16 -4
- package/dist/holmes/governance/provenance-chain.js +19 -4
- package/dist/holmes/governance/provenance-ledger.d.ts +6 -3
- package/dist/holmes/governance/provenance-ledger.js +53 -18
- package/dist/holmes/governance/push-gate-runner.js +11 -7
- package/dist/holmes/governance/recorded-pairs.d.ts +96 -0
- package/dist/holmes/governance/recorded-pairs.js +522 -0
- package/dist/holmes/governance/replica-id.d.ts +1 -1
- package/dist/holmes/governance/replica-id.js +1 -1
- package/dist/holmes/governance/spec-seam.d.ts +59 -0
- package/dist/holmes/governance/spec-seam.js +587 -0
- package/dist/holmes/governance/spend-kinds.d.ts +16 -0
- package/dist/holmes/governance/spend-kinds.js +18 -0
- package/dist/holmes/guardrail/decision-ledger.d.ts +2 -1
- package/dist/holmes/guardrail/decision-ledger.js +2 -1
- package/dist/holmes/guardrail/impact-gate.d.ts +1 -0
- package/dist/holmes/guardrail/impact-gate.js +1 -1
- package/dist/holmes/guardrail/line-continuation.d.ts +8 -0
- package/dist/holmes/guardrail/line-continuation.js +39 -0
- package/dist/holmes/guardrail/operator-person.d.ts +28 -4
- package/dist/holmes/guardrail/operator-person.js +57 -11
- package/dist/holmes/guardrail/refusal-codes.d.ts +8 -3
- package/dist/holmes/guardrail/refusal-codes.js +64 -10
- package/dist/holmes/guardrail/risk-classifier.d.ts +15 -9
- package/dist/holmes/guardrail/risk-classifier.js +228 -16
- package/dist/holmes/guardrail/risk-gate.d.ts +2 -8
- package/dist/holmes/guardrail/risk-gate.js +7 -34
- package/dist/holmes/guardrail/risk-types.d.ts +10 -0
- package/dist/holmes/guardrail/run-plan-scope.js +3 -1
- package/dist/holmes/guardrail/run-refusals.js +24 -8
- package/dist/holmes/guardrail/run-stages.d.ts +5 -0
- package/dist/holmes/guardrail/run-stages.js +25 -5
- package/dist/holmes/guardrail/scope-judgment.js +1 -1
- package/dist/holmes/guardrail/shell-words.js +24 -3
- package/dist/holmes/guardrail/unresolved-write.d.ts +40 -0
- package/dist/holmes/guardrail/unresolved-write.js +556 -0
- package/dist/holmes/guardrail/write-target.d.ts +3 -0
- package/dist/holmes/guardrail/write-target.js +26 -5
- package/dist/holmes/hooks/pre-tool-use.d.ts +105 -1
- package/dist/holmes/hooks/pre-tool-use.js +1134 -167
- package/dist/holmes/hooks/rtm-refresh-child.d.ts +1 -1
- package/dist/holmes/hooks/rtm-refresh-child.js +1 -1
- package/dist/holmes/hooks/stop.d.ts +23 -0
- package/dist/holmes/hooks/stop.js +86 -33
- package/dist/holmes/mcp/approval-adapters.js +3 -1
- package/dist/holmes/mcp/approval-commit.js +3 -2
- package/dist/holmes/mcp/approval-policy.d.ts +2 -1
- package/dist/holmes/mcp/approval-policy.js +3 -1
- package/dist/holmes/mcp/handlers/adoption.d.ts +1 -1
- package/dist/holmes/mcp/handlers/approval-ask.d.ts +3 -0
- package/dist/holmes/mcp/handlers/approval-ask.js +18 -7
- package/dist/holmes/mcp/handlers/entity-integration.d.ts +3 -3
- package/dist/holmes/mcp/handlers/entity-integration.js +29 -11
- package/dist/holmes/mcp/handlers/entity-renumber.d.ts +4 -4
- package/dist/holmes/mcp/handlers/entity-renumber.js +29 -11
- package/dist/holmes/mcp/handlers/entity-store.d.ts +2 -2
- package/dist/holmes/mcp/handlers/entity-store.js +133 -59
- package/dist/holmes/mcp/handlers/operator-inspection.d.ts +9 -5
- package/dist/holmes/mcp/handlers/operator-inspection.js +79 -16
- package/dist/holmes/mcp/handlers/phase-queries.d.ts +1 -1
- package/dist/holmes/mcp/handlers/requirement-triage.d.ts +4 -4
- package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -2
- package/dist/holmes/mcp/handlers/review-evidence.js +35 -11
- package/dist/holmes/mcp/handlers/review-queries.d.ts +5 -0
- package/dist/holmes/mcp/handlers/review-queries.js +8 -1
- package/dist/holmes/mcp/handlers/review-verdict.d.ts +3 -0
- package/dist/holmes/mcp/handlers/review-verdict.js +10 -3
- package/dist/holmes/mcp/handlers/risk-assessment.d.ts +7 -2
- package/dist/holmes/mcp/handlers/risk-assessment.js +34 -12
- package/dist/holmes/mcp/handlers/runtime-binding-tool.d.ts +2 -2
- package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +6 -1
- package/dist/holmes/mcp/handlers/slice-orchestration.js +14 -1
- package/dist/holmes/mcp/handlers/spec-approval.d.ts +15 -3
- package/dist/holmes/mcp/handlers/spec-approval.js +32 -5
- package/dist/holmes/mcp/handlers/spec-authoring.d.ts +2 -2
- package/dist/holmes/mcp/handlers/spec-authoring.js +19 -2
- package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +11 -38
- package/dist/holmes/mcp/handlers/spec-lifecycle.js +441 -94
- package/dist/holmes/mcp/handlers/spec-queries.d.ts +2 -2
- package/dist/holmes/mcp/handlers/taint-screening.d.ts +1 -1
- package/dist/holmes/mcp/handlers/taint-screening.js +2 -2
- package/dist/holmes/mcp/handlers/test-execution.d.ts +1 -1
- package/dist/holmes/mcp/handlers/workspace-queries.d.ts +2 -2
- package/dist/holmes/mcp/handlers.d.ts +89 -79
- package/dist/holmes/mcp/handlers.js +69 -22
- package/dist/holmes/mcp/harness-attestation.d.ts +78 -5
- package/dist/holmes/mcp/harness-attestation.js +325 -53
- package/dist/holmes/mcp/maintenance-analyze.d.ts +1 -1
- package/dist/holmes/mcp/maintenance-analyze.js +9 -9
- package/dist/holmes/mcp/maintenance-evidence.js +31 -2
- package/dist/holmes/mcp/requirement-triage-evidence.js +22 -13
- package/dist/holmes/mcp/server-staleness.js +1 -1
- package/dist/holmes/mcp/server.js +9 -8
- package/dist/holmes/mcp/spec-id-guard.js +1 -1
- package/dist/holmes/mcp/tool-schemas.d.ts +13 -0
- package/dist/holmes/mcp/tool-schemas.js +29 -2
- package/dist/holmes/project/act-root.d.ts +19 -0
- package/dist/holmes/project/act-root.js +100 -0
- package/dist/holmes/project/baseline.js +4 -3
- package/dist/holmes/project/bounded-group.d.ts +47 -0
- package/dist/holmes/project/bounded-group.js +140 -0
- package/dist/holmes/project/bounded-io.d.ts +50 -2
- package/dist/holmes/project/bounded-io.js +138 -6
- package/dist/holmes/project/change-source.js +2 -2
- package/dist/holmes/project/instance-id.d.ts +10 -0
- package/dist/holmes/project/instance-id.js +233 -0
- package/dist/holmes/project/machine-identity.d.ts +25 -0
- package/dist/holmes/project/machine-identity.js +133 -0
- package/dist/holmes/project/owned-lock.d.ts +84 -0
- package/dist/holmes/project/owned-lock.js +263 -0
- package/dist/holmes/project/plain-lock-fs.d.ts +2 -0
- package/dist/holmes/project/plain-lock-fs.js +126 -0
- package/dist/holmes/project/request-lock.d.ts +85 -0
- package/dist/holmes/project/request-lock.js +459 -0
- package/dist/holmes/project/root.d.ts +12 -4
- package/dist/holmes/project/root.js +26 -7
- package/dist/holmes/project/run-records.d.ts +19 -0
- package/dist/holmes/project/run-records.js +94 -12
- package/dist/holmes/project/screen-text.d.ts +94 -0
- package/dist/holmes/project/screen-text.js +763 -0
- package/dist/holmes/project/spend-lock.d.ts +82 -0
- package/dist/holmes/project/spend-lock.js +413 -0
- package/dist/holmes/refresh/freshness-coordinator.d.ts +1 -1
- package/dist/holmes/refresh/freshness-coordinator.js +1 -1
- package/dist/holmes/review/condition-hunk-replay.js +4 -2
- package/dist/holmes/review/confidence-calibration.d.ts +1 -1
- package/dist/holmes/review/confidence-calibration.js +1 -1
- package/dist/holmes/review/content-verify.js +1 -1
- package/dist/holmes/review/hop-ablation.d.ts +4 -4
- package/dist/holmes/review/hop-ablation.js +5 -5
- package/dist/holmes/review/point-in-time-replay.js +12 -3
- package/dist/holmes/review/rank-diagnosis.d.ts +2 -2
- package/dist/holmes/review/rank-diagnosis.js +1 -1
- package/dist/holmes/review/replay-corpus.d.ts +10 -4
- package/dist/holmes/review/replay-corpus.js +25 -9
- package/dist/holmes/review/requirement-triage.js +2 -2
- package/dist/holmes/review/semantic-arm.d.ts +3 -3
- package/dist/holmes/review/semantic-arm.js +3 -3
- package/dist/holmes/review/test-outcomes.js +3 -1
- package/dist/holmes/review/test-runner.d.ts +11 -0
- package/dist/holmes/review/test-runner.js +31 -10
- package/dist/holmes/review/test-selection-breadth.js +2 -2
- package/dist/holmes/review/verdicts.d.ts +105 -8
- package/dist/holmes/review/verdicts.js +640 -36
- package/dist/holmes/rtm/anchor-census.d.ts +9 -0
- package/dist/holmes/rtm/anchor-census.js +151 -0
- package/dist/holmes/rtm/anchor-ids.d.ts +25 -1
- package/dist/holmes/rtm/anchor-ids.js +45 -2
- package/dist/holmes/rtm/comment-ranges.d.ts +2 -0
- package/dist/holmes/rtm/comment-ranges.js +104 -0
- package/dist/holmes/rtm/counted-tests.d.ts +1 -0
- package/dist/holmes/rtm/counted-tests.js +63 -0
- package/dist/holmes/rtm/impact-advisory.d.ts +1 -1
- package/dist/holmes/rtm/known-defects.js +1 -1
- package/dist/holmes/rtm/localize.js +1 -1
- package/dist/holmes/rtm/taint-benchmark.d.ts +1 -1
- package/dist/holmes/rtm/taint-vocabulary.d.ts +1 -1
- package/dist/holmes/rtm/test-scope.d.ts +31 -0
- package/dist/holmes/rtm/test-scope.js +166 -5
- package/dist/holmes/rtm/trace-gaps.js +1 -1
- package/dist/holmes/runtime/dispatch.d.ts +10 -0
- package/dist/holmes/runtime/dispatch.js +12 -1
- package/dist/holmes/semantic/cloud-usage.d.ts +1 -1
- package/dist/holmes/semantic/cloud-usage.js +1 -1
- package/dist/holmes/semantic/unreadable-paths.d.ts +1 -1
- package/dist/holmes/semantic/unreadable-paths.js +1 -1
- package/dist/holmes/spec/approval-blockers.js +1 -1
- package/dist/holmes/spec/entity-store.d.ts +6 -1
- package/dist/holmes/spec/entity-store.js +16 -2
- package/dist/holmes/spec/entity-transaction.d.ts +7 -2
- package/dist/holmes/spec/entity-transaction.js +87 -170
- package/dist/holmes/spec/spec-store.d.ts +12 -6
- package/dist/holmes/spec/spec-store.js +4 -2
- package/dist/holmes/spec/spec-types.js +1 -1
- package/dist/holmes/spec/succession-guard.d.ts +56 -0
- package/dist/holmes/spec/succession-guard.js +187 -0
- package/dist/holmes/spec/succession.d.ts +70 -0
- package/dist/holmes/spec/succession.js +171 -0
- package/dist/holmes/spec/transition-policy.d.ts +2 -2
- package/docs/install-guide.md +9 -3
- package/docs/language-support.md +78 -0
- package/package.json +4 -3
- package/playbooks/author-slice/PLAYBOOK.md +1 -1
- package/playbooks/promote-slice/PLAYBOOK.md +5 -1
- package/playbooks/publish/PLAYBOOK.md +45 -33
- package/dist/holmes/review/manual-baseline.d.ts +0 -209
- package/dist/holmes/review/manual-baseline.js +0 -2847
|
@@ -46,8 +46,17 @@ export declare function gitOnce(root: string, args: string[], kind: GitKind, opt
|
|
|
46
46
|
input?: string;
|
|
47
47
|
timeout?: number;
|
|
48
48
|
env?: NodeJS.ProcessEnv;
|
|
49
|
+
pinned?: JudgmentPins;
|
|
49
50
|
ignoreBlock?: boolean;
|
|
50
51
|
}): SpawnSyncReturns<string>;
|
|
52
|
+
/**
|
|
53
|
+
* @implements A-SPEC-222.13 — gitOnce with stdout as bytes: a batch of blobs is cut at byte offsets, so its output must
|
|
54
|
+
* not pass through a string first (invalid UTF-8 in one blob moved every later offset). Same memory and environment.
|
|
55
|
+
*/
|
|
56
|
+
export declare function gitOnceBuffer(root: string, args: string[], kind: GitKind, opts?: {
|
|
57
|
+
input?: string;
|
|
58
|
+
pinned?: JudgmentPins;
|
|
59
|
+
}): SpawnSyncReturns<Buffer>;
|
|
51
60
|
/** Test seam: forget every blocked root. */
|
|
52
61
|
export declare function resetGitBlocked(): void;
|
|
53
62
|
/**
|
|
@@ -56,6 +65,12 @@ export declare function resetGitBlocked(): void;
|
|
|
56
65
|
* such as `/dev/zero` included). Throws like `readFileSync` does, so callers keep their error handling.
|
|
57
66
|
*/
|
|
58
67
|
export declare function readRegularFileSync(p: string): Buffer;
|
|
68
|
+
/**
|
|
69
|
+
* @implements A-SPEC-102.30 (item 8) — a small regular file, judged on the descriptor that is read: opened non-blocking
|
|
70
|
+
* and without following a link (where the platform can), then fstat'ed for a regular file of at most `max` bytes, so
|
|
71
|
+
* nothing swaps the file between the check and the read. Throws (code EINVAL or EFBIG) otherwise.
|
|
72
|
+
*/
|
|
73
|
+
export declare function readSmallRegularTextSync(p: string, max: number): string;
|
|
59
74
|
/** `readRegularFileSync` as UTF-8 text. */
|
|
60
75
|
export declare function readRegularTextSync(p: string): string;
|
|
61
76
|
/**
|
|
@@ -93,8 +108,41 @@ export declare const REPO_LOCATING_GIT_VARS: readonly ["GIT_DIR", "GIT_WORK_TREE
|
|
|
93
108
|
* a case-folding disk read clean (measured).
|
|
94
109
|
*/
|
|
95
110
|
export declare function underGitPrefix(full: string, prefix: string): string | null;
|
|
96
|
-
|
|
97
|
-
|
|
111
|
+
export declare function gitEnv(env?: NodeJS.ProcessEnv, opts?: {
|
|
112
|
+
attributes?: boolean;
|
|
113
|
+
}): NodeJS.ProcessEnv;
|
|
114
|
+
/**
|
|
115
|
+
* @implements A-SPEC-792.43 — the judgment's own git values, applied after `gitEnv` (gitOnce's `pinned`): no replace
|
|
116
|
+
* objects, the platform's null device as the graft file, no terminal prompt.
|
|
117
|
+
*/
|
|
118
|
+
export declare function judgmentPins(platform?: string): {
|
|
119
|
+
readonly GIT_NO_REPLACE_OBJECTS: "1";
|
|
120
|
+
readonly GIT_GRAFT_FILE: "NUL" | "/dev/null";
|
|
121
|
+
readonly GIT_TERMINAL_PROMPT: "0";
|
|
122
|
+
};
|
|
123
|
+
/** @implements A-SPEC-792.45 — the pins' type and key list come from `judgmentPins`, their one source. */
|
|
124
|
+
export type JudgmentPins = ReturnType<typeof judgmentPins>;
|
|
125
|
+
/**
|
|
126
|
+
* @implements A-SPEC-792.42 — the `-c` overrides for the filters and config-based hooks the configuration names, which
|
|
127
|
+
* no setting switches off: each filter's clean and smudge become `cat`, its process empty and required false; each
|
|
128
|
+
* hook's command becomes `true` (a config-based hook ran on Holmes's update-ref under core.hooksPath=/dev/null —
|
|
129
|
+
* measured). `filters` are the configured filter names. A name holding `=` is a named limit.
|
|
130
|
+
*/
|
|
131
|
+
export declare function inertDriverArgs(cwd: string, env: NodeJS.ProcessEnv): {
|
|
132
|
+
args: string[];
|
|
133
|
+
filters: string[];
|
|
134
|
+
error?: string;
|
|
135
|
+
};
|
|
136
|
+
/**
|
|
137
|
+
* @implements A-SPEC-792.36 — the settings that make Holmes's own git children run no program the repository names
|
|
138
|
+
* and they can switch off: no fsmonitor hook (status ran an agent-set one), no hooks path, no attributes file, no
|
|
139
|
+
* untracked cache. Appended after any `GIT_CONFIG_COUNT` pairs the given environment holds; `gitEnv` passes none, and no
|
|
140
|
+
* GIT_CONFIG_PARAMETERS (which git reads after these pairs). A filter named in `.git/info/attributes` or a tracked
|
|
141
|
+
* `.gitattributes` is outside a setting's reach: `inertDriverArgs` overrides those drivers on Holmes's own writes.
|
|
142
|
+
*/
|
|
143
|
+
export declare function inertGitConfig(env: NodeJS.ProcessEnv, platform?: string, opts?: {
|
|
144
|
+
attributes?: boolean;
|
|
145
|
+
}): NodeJS.ProcessEnv;
|
|
98
146
|
/** Whether a failed git answer means "not judged" rather than "no repository" (round 15: a refusal is not judged too). */
|
|
99
147
|
export declare function gitUnanswered(r: {
|
|
100
148
|
error?: unknown;
|
|
@@ -37,15 +37,20 @@ exports.REPO_LOCATING_GIT_VARS = exports.GIT_MAX_BUFFER = exports.GIT_LONG_TIMEO
|
|
|
37
37
|
exports.gitRootBlocked = gitRootBlocked;
|
|
38
38
|
exports.noteGitFailure = noteGitFailure;
|
|
39
39
|
exports.gitOnce = gitOnce;
|
|
40
|
+
exports.gitOnceBuffer = gitOnceBuffer;
|
|
40
41
|
exports.resetGitBlocked = resetGitBlocked;
|
|
41
42
|
exports.readRegularFileSync = readRegularFileSync;
|
|
43
|
+
exports.readSmallRegularTextSync = readSmallRegularTextSync;
|
|
42
44
|
exports.readRegularTextSync = readRegularTextSync;
|
|
43
45
|
exports.gitAnswerOf = gitAnswerOf;
|
|
44
46
|
exports.gitEntryAbove = gitEntryAbove;
|
|
45
47
|
exports.underGitPrefix = underGitPrefix;
|
|
46
48
|
exports.gitEnv = gitEnv;
|
|
49
|
+
exports.judgmentPins = judgmentPins;
|
|
50
|
+
exports.inertDriverArgs = inertDriverArgs;
|
|
51
|
+
exports.inertGitConfig = inertGitConfig;
|
|
47
52
|
exports.gitUnanswered = gitUnanswered;
|
|
48
|
-
// @implements A-SPEC-734
|
|
53
|
+
// @implements A-SPEC-734, A-SPEC-222.13, A-SPEC-102.30, A-SPEC-102.31
|
|
49
54
|
/**
|
|
50
55
|
* Bounded I/O shared by every caller on a hook, MCP or scan path (A-SPEC-734 round 12).
|
|
51
56
|
*
|
|
@@ -110,12 +115,28 @@ function gitOnce(root, args, kind, opts = {}) {
|
|
|
110
115
|
const error = Object.assign(new Error(`git ${args[0] ?? ''}: not asked — a git child for this root timed out within the last minute`), { code: 'EBLOCKED' });
|
|
111
116
|
return { pid: 0, output: [null, '', ''], stdout: '', stderr: '', status: null, signal: null, error };
|
|
112
117
|
}
|
|
113
|
-
|
|
118
|
+
// @implements A-SPEC-792.43 — the caller's pinned values ride after the shared environment, never through it
|
|
119
|
+
const env = { ...gitEnv(opts.env ?? process.env), ...pinnedOnly(opts.pinned) };
|
|
114
120
|
const r = (0, node_child_process_1.spawnSync)('git', args, { cwd: opts.cwd ?? root, input: opts.input, encoding: 'utf8', timeout: opts.timeout ?? exports.GIT_TIMEOUT_MS, killSignal: 'SIGKILL',
|
|
115
121
|
maxBuffer: exports.GIT_MAX_BUFFER, windowsHide: true, env, stdio: [opts.input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'] });
|
|
116
122
|
noteGitFailure(root, r, kind);
|
|
117
123
|
return r;
|
|
118
124
|
}
|
|
125
|
+
/**
|
|
126
|
+
* @implements A-SPEC-222.13 — gitOnce with stdout as bytes: a batch of blobs is cut at byte offsets, so its output must
|
|
127
|
+
* not pass through a string first (invalid UTF-8 in one blob moved every later offset). Same memory and environment.
|
|
128
|
+
*/
|
|
129
|
+
function gitOnceBuffer(root, args, kind, opts = {}) {
|
|
130
|
+
if (gitRootBlocked(root, kind)) {
|
|
131
|
+
const error = Object.assign(new Error(`git ${args[0] ?? ''}: not asked — a git child for this root timed out within the last minute`), { code: 'EBLOCKED' });
|
|
132
|
+
return { pid: 0, output: [null, Buffer.alloc(0), Buffer.alloc(0)], stdout: Buffer.alloc(0), stderr: Buffer.alloc(0), status: null, signal: null, error };
|
|
133
|
+
}
|
|
134
|
+
const env = { ...gitEnv(process.env), ...pinnedOnly(opts.pinned) };
|
|
135
|
+
const r = (0, node_child_process_1.spawnSync)('git', args, { cwd: root, input: opts.input, timeout: exports.GIT_TIMEOUT_MS, killSignal: 'SIGKILL',
|
|
136
|
+
maxBuffer: exports.GIT_MAX_BUFFER, windowsHide: true, env, stdio: [opts.input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'] });
|
|
137
|
+
noteGitFailure(root, r, kind);
|
|
138
|
+
return r;
|
|
139
|
+
}
|
|
119
140
|
/** Test seam: forget every blocked root. */
|
|
120
141
|
function resetGitBlocked() { BLOCKED.clear(); }
|
|
121
142
|
/**
|
|
@@ -138,6 +159,41 @@ function readRegularFileSync(p) {
|
|
|
138
159
|
fs.closeSync(fd);
|
|
139
160
|
}
|
|
140
161
|
}
|
|
162
|
+
/**
|
|
163
|
+
* @implements A-SPEC-102.30 (item 8) — a small regular file, judged on the descriptor that is read: opened non-blocking
|
|
164
|
+
* and without following a link (where the platform can), then fstat'ed for a regular file of at most `max` bytes, so
|
|
165
|
+
* nothing swaps the file between the check and the read. Throws (code EINVAL or EFBIG) otherwise.
|
|
166
|
+
*/
|
|
167
|
+
function readSmallRegularTextSync(p, max) {
|
|
168
|
+
const c = fs.constants;
|
|
169
|
+
const flags = c.O_RDONLY | (typeof c.O_NONBLOCK === 'number' ? c.O_NONBLOCK : 0) | (typeof c.O_NOFOLLOW === 'number' ? c.O_NOFOLLOW : 0);
|
|
170
|
+
const fd = fs.openSync(p, flags);
|
|
171
|
+
try {
|
|
172
|
+
const st = fs.fstatSync(fd);
|
|
173
|
+
const tooBig = () => { const err = new Error(`larger than ${max} bytes: ${p}`); err.code = 'EFBIG'; throw err; };
|
|
174
|
+
if (!st.isFile()) {
|
|
175
|
+
const err = new Error(`not a regular file: ${p}`);
|
|
176
|
+
err.code = 'EINVAL';
|
|
177
|
+
throw err;
|
|
178
|
+
}
|
|
179
|
+
if (st.size > max)
|
|
180
|
+
tooBig();
|
|
181
|
+
// @implements A-SPEC-102.31 — at most max + 1 bytes: readFileSync(fd) sized the read again, so a file that grew after
|
|
182
|
+
// the fstat was read whole (A, judged); one byte past the bound refuses it
|
|
183
|
+
const buf = Buffer.alloc(max + 1);
|
|
184
|
+
let n = 0;
|
|
185
|
+
for (let r = -1; r !== 0 && n < buf.length;) {
|
|
186
|
+
r = fs.readSync(fd, buf, n, buf.length - n, null);
|
|
187
|
+
n += r;
|
|
188
|
+
}
|
|
189
|
+
if (n > max)
|
|
190
|
+
tooBig();
|
|
191
|
+
return buf.subarray(0, n).toString('utf8');
|
|
192
|
+
}
|
|
193
|
+
finally {
|
|
194
|
+
fs.closeSync(fd);
|
|
195
|
+
}
|
|
196
|
+
}
|
|
141
197
|
/** `readRegularFileSync` as UTF-8 text. */
|
|
142
198
|
function readRegularTextSync(p) {
|
|
143
199
|
return readRegularFileSync(p).toString('utf8');
|
|
@@ -201,11 +257,87 @@ function underGitPrefix(full, prefix) {
|
|
|
201
257
|
return null;
|
|
202
258
|
return have.slice(want.length).join('/');
|
|
203
259
|
}
|
|
204
|
-
/**
|
|
205
|
-
|
|
260
|
+
/**
|
|
261
|
+
* A git child's environment: the caller's, without the variables that relocate the repository (round 17).
|
|
262
|
+
* @implements A-SPEC-792.42 — and without any other inherited GIT_* variable but these two: the nine relocating ones
|
|
263
|
+
* left GIT_CONFIG_PARAMETERS (read after the GIT_CONFIG_COUNT pairs, so it beat the inert values — measured),
|
|
264
|
+
* GIT_CONFIG_GLOBAL/SYSTEM, GIT_EXEC_PATH, GIT_EXTERNAL_DIFF and GIT_ATTR_SOURCE to steer Holmes's git.
|
|
265
|
+
*/
|
|
266
|
+
// @implements A-SPEC-792.43 — the two its sealed text names; the judgment's own values ride after it as `pinned`
|
|
267
|
+
// (judgmentPins), not through this list (a NUL graft file was kept on POSIX and read a top-level `NUL` — measured)
|
|
268
|
+
const GIT_ENV_KEPT = new Set(['GIT_TERMINAL_PROMPT', 'GIT_CONFIG_NOSYSTEM']);
|
|
269
|
+
function gitEnv(env = process.env, opts = {}) {
|
|
270
|
+
const out = {};
|
|
271
|
+
for (const [k, v] of Object.entries(env))
|
|
272
|
+
if (!/^GIT_/i.test(k) || GIT_ENV_KEPT.has(k.toUpperCase()))
|
|
273
|
+
out[k] = v;
|
|
274
|
+
return inertGitConfig(out, process.platform, opts);
|
|
275
|
+
}
|
|
276
|
+
/**
|
|
277
|
+
* @implements A-SPEC-792.43 — the judgment's own git values, applied after `gitEnv` (gitOnce's `pinned`): no replace
|
|
278
|
+
* objects, the platform's null device as the graft file, no terminal prompt.
|
|
279
|
+
*/
|
|
280
|
+
function judgmentPins(platform = process.platform) {
|
|
281
|
+
return { GIT_NO_REPLACE_OBJECTS: '1', GIT_GRAFT_FILE: platform === 'win32' ? 'NUL' : '/dev/null', GIT_TERMINAL_PROMPT: '0' };
|
|
282
|
+
}
|
|
283
|
+
/** @implements A-SPEC-792.44 — the only keys `pinned` carries past the sanitising, whatever a caller hands over. */
|
|
284
|
+
const PIN_KEYS = Object.keys(judgmentPins());
|
|
285
|
+
function pinnedOnly(pinned) {
|
|
286
|
+
const out = {};
|
|
287
|
+
if (pinned)
|
|
288
|
+
for (const k of PIN_KEYS)
|
|
289
|
+
out[k] = pinned[k];
|
|
290
|
+
return out;
|
|
291
|
+
}
|
|
292
|
+
/**
|
|
293
|
+
* @implements A-SPEC-792.42 — the `-c` overrides for the filters and config-based hooks the configuration names, which
|
|
294
|
+
* no setting switches off: each filter's clean and smudge become `cat`, its process empty and required false; each
|
|
295
|
+
* hook's command becomes `true` (a config-based hook ran on Holmes's update-ref under core.hooksPath=/dev/null —
|
|
296
|
+
* measured). `filters` are the configured filter names. A name holding `=` is a named limit.
|
|
297
|
+
*/
|
|
298
|
+
function inertDriverArgs(cwd, env) {
|
|
299
|
+
const r = (0, node_child_process_1.spawnSync)('git', ['config', '--name-only', '--get-regexp', '^(filter|hook)\\.'], { cwd, encoding: 'utf8', env, timeout: exports.GIT_TIMEOUT_MS, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: exports.GIT_MAX_BUFFER });
|
|
300
|
+
// @implements A-SPEC-792.43 — a read that failed is not "none configured" (exit 1): the callers refuse rather than run
|
|
301
|
+
// without the overrides
|
|
302
|
+
if (r.error || (r.status !== 0 && r.status !== 1)) {
|
|
303
|
+
return { args: [], filters: [], error: `the configured filter and hook names could not be read (${r.error ? r.error.code ?? r.error.message : `exit ${r.status ?? r.signal}`})` };
|
|
304
|
+
}
|
|
305
|
+
const filters = new Set();
|
|
306
|
+
const hooks = new Set();
|
|
307
|
+
for (const line of String(r.stdout ?? '').split('\n')) {
|
|
308
|
+
const m = /^(filter|hook)\.(.+)\.[^.]+$/i.exec(line.trim());
|
|
309
|
+
if (m)
|
|
310
|
+
(m[1].toLowerCase() === 'filter' ? filters : hooks).add(m[2]);
|
|
311
|
+
}
|
|
312
|
+
const args = [
|
|
313
|
+
...[...filters].flatMap((n) => ['clean=cat', 'smudge=cat', 'process=', 'required=false'].flatMap((kv) => ['-c', `filter.${n}.${kv}`])),
|
|
314
|
+
...[...hooks].flatMap((n) => ['-c', `hook.${n}.command=true`]),
|
|
315
|
+
];
|
|
316
|
+
return { args, filters: [...filters] };
|
|
317
|
+
}
|
|
318
|
+
/**
|
|
319
|
+
* @implements A-SPEC-792.36 — the settings that make Holmes's own git children run no program the repository names
|
|
320
|
+
* and they can switch off: no fsmonitor hook (status ran an agent-set one), no hooks path, no attributes file, no
|
|
321
|
+
* untracked cache. Appended after any `GIT_CONFIG_COUNT` pairs the given environment holds; `gitEnv` passes none, and no
|
|
322
|
+
* GIT_CONFIG_PARAMETERS (which git reads after these pairs). A filter named in `.git/info/attributes` or a tracked
|
|
323
|
+
* `.gitattributes` is outside a setting's reach: `inertDriverArgs` overrides those drivers on Holmes's own writes.
|
|
324
|
+
*/
|
|
325
|
+
function inertGitConfig(env, platform = process.platform, opts = {}) {
|
|
326
|
+
const nul = platform === 'win32' ? 'NUL' : '/dev/null';
|
|
206
327
|
const out = { ...env };
|
|
207
|
-
|
|
208
|
-
|
|
328
|
+
const n = Number.parseInt(String(out.GIT_CONFIG_COUNT ?? '0'), 10);
|
|
329
|
+
let i = Number.isFinite(n) && n > 0 ? n : 0;
|
|
330
|
+
// @implements A-SPEC-792.43 — `attributes: true` leaves core.attributesFile as configured, for a check that runs no
|
|
331
|
+
// program (check-attr) and so must read every attributes source
|
|
332
|
+
const pairs = [['core.fsmonitor', 'false'], ['core.hooksPath', nul], ...(opts.attributes ? [] : [['core.attributesFile', nul]]), ['core.untrackedCache', 'false']];
|
|
333
|
+
for (const [k, v] of pairs) {
|
|
334
|
+
out[`GIT_CONFIG_KEY_${i}`] = k;
|
|
335
|
+
out[`GIT_CONFIG_VALUE_${i}`] = v;
|
|
336
|
+
i++;
|
|
337
|
+
}
|
|
338
|
+
out.GIT_CONFIG_COUNT = String(i);
|
|
339
|
+
// @implements A-SPEC-792.39 — no opportunistic index rewrite (and so no post-index-change) from a status.
|
|
340
|
+
out.GIT_OPTIONAL_LOCKS = '0';
|
|
209
341
|
return out;
|
|
210
342
|
}
|
|
211
343
|
/** Whether a failed git answer means "not judged" rather than "no repository" (round 15: a refusal is not judged too). */
|
|
@@ -36,7 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
|
|
|
36
36
|
exports.EMPTY_CHANGE_SET = exports.GitChangeSource = exports.SnapshotChangeSource = exports.hashOf = exports.isDerivedState = void 0;
|
|
37
37
|
exports.hashTree = hashTree;
|
|
38
38
|
exports.diffHashes = diffHashes;
|
|
39
|
-
// @implements A-SPEC-128, A-SPEC-734
|
|
39
|
+
// @implements A-SPEC-128, A-SPEC-734, A-SPEC-794.58
|
|
40
40
|
const fs = __importStar(require("node:fs"));
|
|
41
41
|
const path = __importStar(require("node:path"));
|
|
42
42
|
const node_crypto_1 = require("node:crypto");
|
|
@@ -195,7 +195,7 @@ class GitChangeSource {
|
|
|
195
195
|
// (even one that walks up to the same `.ax`) would tag paths against the wrong base. Both sides
|
|
196
196
|
// go through ONE canonicaliser: the old `fs.realpathSync(root)` here was the JS realpath, which
|
|
197
197
|
// keeps Windows 8.3 aliases the top-level side had already expanded — measured 2026-08-23, the
|
|
198
|
-
// same directory spelled `C:\
|
|
198
|
+
// same directory spelled `C:\WORKSP~1\…` threw as a mismatch.
|
|
199
199
|
if (this.topLevel && (0, root_1.canonicalPath)(path.resolve(root)) !== this.topLevel) {
|
|
200
200
|
throw new Error(`GitChangeSource: root must be the git top-level (got ${root}, top-level is ${this.topLevel})`);
|
|
201
201
|
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
export declare const INSTANCE_ID_RELPATH = ".ax/state/instance-id.json";
|
|
2
|
+
/** Points where a test pauses this creator while another runs. */
|
|
3
|
+
export interface InstanceIdHooks {
|
|
4
|
+
beforePublish?: () => void;
|
|
5
|
+
beforeAside?: () => void;
|
|
6
|
+
}
|
|
7
|
+
/** The instance id, or null when it is absent, malformed or another directory's. Never writes. */
|
|
8
|
+
export declare function readInstanceId(root: string): string | null;
|
|
9
|
+
/** This clone's instance id, created when absent or mismatched. Refuses without an existing `.ax`. */
|
|
10
|
+
export declare function ensureInstanceId(root: string, hooks?: InstanceIdHooks): string;
|
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
+
if (k2 === undefined) k2 = k;
|
|
4
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
+
}
|
|
8
|
+
Object.defineProperty(o, k2, desc);
|
|
9
|
+
}) : (function(o, m, k, k2) {
|
|
10
|
+
if (k2 === undefined) k2 = k;
|
|
11
|
+
o[k2] = m[k];
|
|
12
|
+
}));
|
|
13
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
14
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
15
|
+
}) : function(o, v) {
|
|
16
|
+
o["default"] = v;
|
|
17
|
+
});
|
|
18
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
19
|
+
var ownKeys = function(o) {
|
|
20
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
21
|
+
var ar = [];
|
|
22
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
23
|
+
return ar;
|
|
24
|
+
};
|
|
25
|
+
return ownKeys(o);
|
|
26
|
+
};
|
|
27
|
+
return function (mod) {
|
|
28
|
+
if (mod && mod.__esModule) return mod;
|
|
29
|
+
var result = {};
|
|
30
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
31
|
+
__setModuleDefault(result, mod);
|
|
32
|
+
return result;
|
|
33
|
+
};
|
|
34
|
+
})();
|
|
35
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
+
exports.INSTANCE_ID_RELPATH = void 0;
|
|
37
|
+
exports.readInstanceId = readInstanceId;
|
|
38
|
+
exports.ensureInstanceId = ensureInstanceId;
|
|
39
|
+
// @implements A-SPEC-794.2, A-SPEC-794.6
|
|
40
|
+
/**
|
|
41
|
+
* This clone's instance id (design draft 4 §1.1): what "issued by this replica" means for approval cycles. The S1
|
|
42
|
+
* cycles that read it were reverted for 0.40.0 (A-SPEC-794.30); the id stays, as the S2 skeleton made it. It is a local fact in `.ax/state/instance-id.json`, never the HOLMES_REPLICA_ID environment
|
|
43
|
+
* value, which a process can set.
|
|
44
|
+
*
|
|
45
|
+
* - The file is `{ v: 1, id, realpath, dev, ino }`, the last three being those of `.ax/state`. A file whose dev and
|
|
46
|
+
* ino do not match was copied or moved with its directory and names another instance: it reads as none. realpath is
|
|
47
|
+
* kept for a reader and not compared, so letter case or a mount path does not change the id (A-SPEC-794.6).
|
|
48
|
+
* - A read never creates it. A missing file is published by a no-clobber link, so two creators agree on one id.
|
|
49
|
+
* - A mismatched file is repaired only under the repair lock `instance-id.lock` (exclusive create; one older than 30 s
|
|
50
|
+
* is taken over by inode). Under the lock the file is judged again through one fd (bytes and fstat), moved aside
|
|
51
|
+
* only while that inode is still at the path, and a moved file that is not the judged one is linked back.
|
|
52
|
+
* - Nothing is created without an existing `.ax`.
|
|
53
|
+
*
|
|
54
|
+
* Limits: a repairer paused past the 30 s takeover can race a new one; the inode checks keep a just-published file,
|
|
55
|
+
* but two ids can then be returned. A file system whose device number changes across mounts renews the id.
|
|
56
|
+
*/
|
|
57
|
+
const fs = __importStar(require("node:fs"));
|
|
58
|
+
const path = __importStar(require("node:path"));
|
|
59
|
+
const node_crypto_1 = require("node:crypto");
|
|
60
|
+
exports.INSTANCE_ID_RELPATH = '.ax/state/instance-id.json';
|
|
61
|
+
const LOCK_RELPATH = '.ax/state/instance-id.lock';
|
|
62
|
+
const LOCK_STALE_MS = 30_000;
|
|
63
|
+
const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
|
|
64
|
+
const lstat = (p) => { try {
|
|
65
|
+
return fs.lstatSync(p);
|
|
66
|
+
}
|
|
67
|
+
catch {
|
|
68
|
+
return undefined;
|
|
69
|
+
} };
|
|
70
|
+
function stateFingerprint(root) {
|
|
71
|
+
const state = path.join(root, '.ax', 'state');
|
|
72
|
+
const s = lstat(state);
|
|
73
|
+
if (!s?.isDirectory())
|
|
74
|
+
return null;
|
|
75
|
+
try {
|
|
76
|
+
return { realpath: fs.realpathSync(state), dev: s.dev, ino: s.ino };
|
|
77
|
+
}
|
|
78
|
+
catch {
|
|
79
|
+
return null;
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
/** The file as one fd sees it: its id when it matches (or null), and the inode that was judged. Absent: undefined. */
|
|
83
|
+
function judge(root) {
|
|
84
|
+
const fp = stateFingerprint(root);
|
|
85
|
+
let fd;
|
|
86
|
+
try {
|
|
87
|
+
fd = fs.openSync(path.join(root, exports.INSTANCE_ID_RELPATH), fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
|
|
88
|
+
}
|
|
89
|
+
catch {
|
|
90
|
+
return undefined;
|
|
91
|
+
}
|
|
92
|
+
try {
|
|
93
|
+
const st = fs.fstatSync(fd);
|
|
94
|
+
let r = null;
|
|
95
|
+
try {
|
|
96
|
+
r = JSON.parse(fs.readFileSync(fd, 'utf8'));
|
|
97
|
+
}
|
|
98
|
+
catch {
|
|
99
|
+
r = null;
|
|
100
|
+
}
|
|
101
|
+
const o = (typeof r === 'object' && r !== null ? r : {});
|
|
102
|
+
const ok = fp !== null && o.v === 1 && typeof o.id === 'string' && UUID_V4.test(o.id) && o.dev === fp.dev && o.ino === fp.ino;
|
|
103
|
+
return { id: ok ? o.id : null, ino: st.ino, dev: st.dev };
|
|
104
|
+
}
|
|
105
|
+
finally {
|
|
106
|
+
fs.closeSync(fd);
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
/** The instance id, or null when it is absent, malformed or another directory's. Never writes. */
|
|
110
|
+
function readInstanceId(root) {
|
|
111
|
+
return judge(root)?.id ?? null;
|
|
112
|
+
}
|
|
113
|
+
/** Publish a new id by link; true when it is in place, false when another file took the name first. */
|
|
114
|
+
function publish(root, hooks) {
|
|
115
|
+
const fp = stateFingerprint(root);
|
|
116
|
+
if (!fp)
|
|
117
|
+
throw new Error('.ax/state is not a directory; no instance id is created.');
|
|
118
|
+
const temp = path.join(root, '.ax', 'state', `.instance-id.${(0, node_crypto_1.randomUUID)()}.tmp`);
|
|
119
|
+
fs.writeFileSync(temp, JSON.stringify({ v: 1, id: (0, node_crypto_1.randomUUID)(), ...fp }), { flag: 'wx', mode: 0o600 });
|
|
120
|
+
try {
|
|
121
|
+
hooks.beforePublish?.();
|
|
122
|
+
fs.linkSync(temp, path.join(root, exports.INSTANCE_ID_RELPATH));
|
|
123
|
+
return true;
|
|
124
|
+
}
|
|
125
|
+
catch (e) {
|
|
126
|
+
if (e.code === 'EEXIST')
|
|
127
|
+
return false;
|
|
128
|
+
throw e;
|
|
129
|
+
}
|
|
130
|
+
finally {
|
|
131
|
+
try {
|
|
132
|
+
fs.unlinkSync(temp);
|
|
133
|
+
}
|
|
134
|
+
catch { /* removed already */ }
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
/** Run `fn` under the repair lock, or answer null when another repairer holds it. */
|
|
138
|
+
function underRepairLock(root, fn) {
|
|
139
|
+
const lock = path.join(root, LOCK_RELPATH);
|
|
140
|
+
let fd;
|
|
141
|
+
try {
|
|
142
|
+
fd = fs.openSync(lock, 'wx', 0o600);
|
|
143
|
+
}
|
|
144
|
+
catch (e) {
|
|
145
|
+
if (e.code !== 'EEXIST')
|
|
146
|
+
throw e;
|
|
147
|
+
const s = lstat(lock);
|
|
148
|
+
if (s && Date.now() - s.mtimeMs > LOCK_STALE_MS) {
|
|
149
|
+
// take over an abandoned lock: only the inode judged stale is removed
|
|
150
|
+
const again = lstat(lock);
|
|
151
|
+
if (again && again.ino === s.ino && again.dev === s.dev) {
|
|
152
|
+
try {
|
|
153
|
+
fs.unlinkSync(lock);
|
|
154
|
+
}
|
|
155
|
+
catch { /* raced */ }
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
return null;
|
|
159
|
+
}
|
|
160
|
+
fs.closeSync(fd);
|
|
161
|
+
const mine = lstat(lock);
|
|
162
|
+
try {
|
|
163
|
+
return fn();
|
|
164
|
+
}
|
|
165
|
+
finally {
|
|
166
|
+
const now = lstat(lock);
|
|
167
|
+
if (now && mine && now.ino === mine.ino && now.dev === mine.dev) {
|
|
168
|
+
try {
|
|
169
|
+
fs.unlinkSync(lock);
|
|
170
|
+
}
|
|
171
|
+
catch { /* gone */ }
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
/** Move the judged inode aside; a file that is not the judged one is linked back. */
|
|
176
|
+
function setAside(root, judged) {
|
|
177
|
+
const file = path.join(root, exports.INSTANCE_ID_RELPATH);
|
|
178
|
+
const aside = `${file}.stale-${(0, node_crypto_1.randomUUID)()}`;
|
|
179
|
+
try {
|
|
180
|
+
fs.renameSync(file, aside);
|
|
181
|
+
}
|
|
182
|
+
catch {
|
|
183
|
+
return;
|
|
184
|
+
}
|
|
185
|
+
const moved = lstat(aside);
|
|
186
|
+
if (moved && (moved.dev !== judged.dev || moved.ino !== judged.ino)) {
|
|
187
|
+
try {
|
|
188
|
+
fs.linkSync(aside, file);
|
|
189
|
+
fs.unlinkSync(aside);
|
|
190
|
+
}
|
|
191
|
+
catch { /* a newer file is in place; this one stays aside */ }
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
/** This clone's instance id, created when absent or mismatched. Refuses without an existing `.ax`. */
|
|
195
|
+
function ensureInstanceId(root, hooks = {}) {
|
|
196
|
+
if (!lstat(path.join(root, '.ax'))?.isDirectory())
|
|
197
|
+
throw new Error('An instance id is created only inside an existing .ax directory.');
|
|
198
|
+
const state = path.join(root, '.ax', 'state');
|
|
199
|
+
if (!lstat(state)) {
|
|
200
|
+
try {
|
|
201
|
+
fs.mkdirSync(state);
|
|
202
|
+
}
|
|
203
|
+
catch (e) {
|
|
204
|
+
if (e.code !== 'EEXIST')
|
|
205
|
+
throw e;
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
for (let attempt = 0; attempt < 200; attempt++) {
|
|
209
|
+
const seen = judge(root);
|
|
210
|
+
if (seen?.id)
|
|
211
|
+
return seen.id;
|
|
212
|
+
if (seen === undefined) {
|
|
213
|
+
publish(root, hooks);
|
|
214
|
+
continue;
|
|
215
|
+
}
|
|
216
|
+
underRepairLock(root, () => {
|
|
217
|
+
const now = judge(root);
|
|
218
|
+
if (now === undefined || now.id !== null)
|
|
219
|
+
return;
|
|
220
|
+
hooks.beforeAside?.();
|
|
221
|
+
setAside(root, now);
|
|
222
|
+
if (judge(root) === undefined)
|
|
223
|
+
publish(root, hooks);
|
|
224
|
+
});
|
|
225
|
+
if (attempt > 0) {
|
|
226
|
+
try {
|
|
227
|
+
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
|
|
228
|
+
}
|
|
229
|
+
catch { /* retry */ }
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
throw new Error('The instance id kept changing under this process; no id is returned.');
|
|
233
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
export declare const IDENTITY_TIMEOUT_MS = 1000;
|
|
2
|
+
export interface IdentityDeps {
|
|
3
|
+
platform: NodeJS.Platform;
|
|
4
|
+
exec: (file: string, args: string[], opts: {
|
|
5
|
+
timeout: number;
|
|
6
|
+
env: Record<string, string>;
|
|
7
|
+
encoding: 'utf8';
|
|
8
|
+
stdio: ['ignore', 'pipe', 'ignore'];
|
|
9
|
+
}) => string;
|
|
10
|
+
readFile: (p: string) => string;
|
|
11
|
+
statIno: (p: string) => number;
|
|
12
|
+
/** Windows only: where reg.exe lives. */
|
|
13
|
+
systemRoot?: string;
|
|
14
|
+
/** The clock a null value's retry is timed on. */
|
|
15
|
+
now?: () => number;
|
|
16
|
+
}
|
|
17
|
+
/** A-SPEC-245.10 (low): a null is kept this long, not for the process's life — a read that timed out under load retries. */
|
|
18
|
+
export declare const IDENTITY_NULL_RETRY_MS = 60000;
|
|
19
|
+
export interface IdentityReader {
|
|
20
|
+
bootId(): string | null;
|
|
21
|
+
hostId(): string | null;
|
|
22
|
+
}
|
|
23
|
+
export declare function createIdentityReader(deps: IdentityDeps): IdentityReader;
|
|
24
|
+
export declare function bootId(): string | null;
|
|
25
|
+
export declare function hostId(): string | null;
|