dsh-skill-pool 0.3.7 → 0.4.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/CONTRACTS-v3.md +129 -12
- package/README.md +173 -14
- package/client.js +341 -73
- package/index.js +58 -16
- package/package.json +8 -2
- package/src/activation.js +584 -115
- package/src/inventory.js +6 -1
- package/src/mount.js +9 -4
- package/src/rules.js +29 -0
- package/src/store.js +494 -28
- package/src/web-api.js +413 -69
package/src/store.js
CHANGED
|
@@ -31,14 +31,33 @@
|
|
|
31
31
|
* @module dsh-skill-pool/store
|
|
32
32
|
*/
|
|
33
33
|
|
|
34
|
+
import { AsyncLocalStorage } from 'node:async_hooks'
|
|
34
35
|
import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
|
|
35
|
-
import { dirname, join } from 'node:path'
|
|
36
|
+
import { dirname, join, resolve as resolvePath } from 'node:path'
|
|
36
37
|
import { homedir } from 'node:os'
|
|
37
38
|
import { groupKeyOfSource } from './rules.js'
|
|
38
39
|
|
|
39
40
|
/** Current document version. */
|
|
40
41
|
export const STATE_VERSION = 4
|
|
41
42
|
|
|
43
|
+
/**
|
|
44
|
+
* Absolute state-file paths this Node process has observed.
|
|
45
|
+
*
|
|
46
|
+
* A new `StateStore` (for example after an in-process plugin reload) must not
|
|
47
|
+
* forget that a file existed and mistake its disappearance for a first run.
|
|
48
|
+
* This is an in-memory set: it creates no file, survives module reloads in the
|
|
49
|
+
* same process through `globalThis`, and intentionally cannot survive a Host
|
|
50
|
+
* restart (a deleted file and a genuine first run are then indistinguishable).
|
|
51
|
+
*/
|
|
52
|
+
const OBSERVED_STATE_FILES_KEY = Symbol.for('dsh-skill-pool.observed-state-files')
|
|
53
|
+
const observedStateFiles =
|
|
54
|
+
globalThis[OBSERVED_STATE_FILES_KEY] instanceof Set
|
|
55
|
+
? globalThis[OBSERVED_STATE_FILES_KEY]
|
|
56
|
+
: (globalThis[OBSERVED_STATE_FILES_KEY] = new Set())
|
|
57
|
+
|
|
58
|
+
/** Group keys that would mutate the normalized map's prototype. */
|
|
59
|
+
const FORBIDDEN_GROUP_KEYS = new Set(['__proto__', 'prototype', 'constructor'])
|
|
60
|
+
|
|
42
61
|
/** The one older version this module upgrades instead of discarding. */
|
|
43
62
|
export const LEGACY_VERSION = 3
|
|
44
63
|
|
|
@@ -61,7 +80,7 @@ export const GIT_PROVIDERS = ['github', 'gitlab']
|
|
|
61
80
|
export const CHECK_STATUSES = ['up-to-date', 'update-available', 'error']
|
|
62
81
|
|
|
63
82
|
/** Switches the panel may patch. */
|
|
64
|
-
export const SETTING_KEYS = ['enabled', 'mcpGate', '
|
|
83
|
+
export const SETTING_KEYS = ['enabled', 'mcpGate', 'gateDefaultSkills']
|
|
65
84
|
|
|
66
85
|
/** Conservative identifier grammar for resource names and mode ids. */
|
|
67
86
|
const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$/
|
|
@@ -174,7 +193,7 @@ function cleanSubdir(value) {
|
|
|
174
193
|
|
|
175
194
|
/** Default settings of a fresh document (§2.1). */
|
|
176
195
|
export function defaultSettings() {
|
|
177
|
-
return { enabled: true, mcpGate: true,
|
|
196
|
+
return { enabled: true, mcpGate: true, gateDefaultSkills: false }
|
|
178
197
|
}
|
|
179
198
|
|
|
180
199
|
/** A fresh, empty document. */
|
|
@@ -498,7 +517,6 @@ function migrateV3(source) {
|
|
|
498
517
|
const settings = {
|
|
499
518
|
enabled: rawSettings.enabled !== false,
|
|
500
519
|
mcpGate: rawSettings.mcpGate !== false,
|
|
501
|
-
injectSummary: rawSettings.injectSummary !== false,
|
|
502
520
|
gateDefaultSkills: rawSettings.gateDefaultSkills === true,
|
|
503
521
|
}
|
|
504
522
|
const sources = {}
|
|
@@ -563,7 +581,6 @@ export function normalizeState(raw) {
|
|
|
563
581
|
const settings = {
|
|
564
582
|
enabled: rawSettings.enabled !== false,
|
|
565
583
|
mcpGate: rawSettings.mcpGate !== false,
|
|
566
|
-
injectSummary: rawSettings.injectSummary !== false,
|
|
567
584
|
gateDefaultSkills: rawSettings.gateDefaultSkills === true,
|
|
568
585
|
}
|
|
569
586
|
|
|
@@ -586,6 +603,297 @@ export function normalizeState(raw) {
|
|
|
586
603
|
}
|
|
587
604
|
}
|
|
588
605
|
|
|
606
|
+
/** Top-level sections every complete v4 document must carry as plain objects. */
|
|
607
|
+
const STATE_SECTIONS = ['settings', 'skills', 'mcp', 'sources', 'groups']
|
|
608
|
+
|
|
609
|
+
/**
|
|
610
|
+
* A state document that cannot be used safely.
|
|
611
|
+
*
|
|
612
|
+
* The code is intentionally stable for the HTTP/status surfaces; the message is
|
|
613
|
+
* a fixed explanation and never contains file bytes, member definitions or
|
|
614
|
+
* credentials. Callers either keep their previous gate (an already-live Agent)
|
|
615
|
+
* or fail closed (a new Agent).
|
|
616
|
+
*/
|
|
617
|
+
export class StateReadError extends Error {
|
|
618
|
+
/**
|
|
619
|
+
* @param {string} code - stable error code such as `resource-pool/state-invalid-json`.
|
|
620
|
+
* @param {string} message - safe explanation, never document content.
|
|
621
|
+
*/
|
|
622
|
+
constructor(code, message) {
|
|
623
|
+
// Keep diagnostics fixed, single-line and bounded: map keys and version
|
|
624
|
+
// values come from the file and may contain secrets or newlines.
|
|
625
|
+
super(String(message).replace(/[\r\n]+/g, ' ').slice(0, 240))
|
|
626
|
+
this.name = 'StateReadError'
|
|
627
|
+
this.code = code
|
|
628
|
+
this.status = 500
|
|
629
|
+
}
|
|
630
|
+
}
|
|
631
|
+
|
|
632
|
+
/** Throw the one "this document cannot be trusted" error. */
|
|
633
|
+
function invalidDocument(detail) {
|
|
634
|
+
throw new StateReadError(
|
|
635
|
+
'resource-pool/state-invalid-document',
|
|
636
|
+
`state file is not a valid resource-pool document (${detail}); refusing to overwrite or use it`,
|
|
637
|
+
)
|
|
638
|
+
}
|
|
639
|
+
|
|
640
|
+
/** Require a plain object. */
|
|
641
|
+
function requireObject(value, what) {
|
|
642
|
+
if (!isObject(value)) invalidDocument(`${what} must be an object`)
|
|
643
|
+
}
|
|
644
|
+
|
|
645
|
+
/** Require a boolean when the property is present. */
|
|
646
|
+
function optionalBoolean(value, what) {
|
|
647
|
+
if (value !== undefined && typeof value !== 'boolean') invalidDocument(`${what} must be a boolean`)
|
|
648
|
+
}
|
|
649
|
+
|
|
650
|
+
/** Require a string when the property is present. */
|
|
651
|
+
function optionalStringField(value, what, limit = 4096) {
|
|
652
|
+
if (value === undefined) return
|
|
653
|
+
if (typeof value !== 'string' || value.length > limit) invalidDocument(`${what} must be a string of at most ${limit} characters`)
|
|
654
|
+
}
|
|
655
|
+
|
|
656
|
+
/** Require an array of conservative names. */
|
|
657
|
+
function requireNameList(value, what) {
|
|
658
|
+
if (!Array.isArray(value)) invalidDocument(`${what} must be an array of names`)
|
|
659
|
+
for (const item of value) {
|
|
660
|
+
if (typeof item !== 'string' || cleanName(item) !== item) invalidDocument(`${what} contains an invalid name`)
|
|
661
|
+
}
|
|
662
|
+
}
|
|
663
|
+
|
|
664
|
+
/** Require an array of absolute workspace paths. */
|
|
665
|
+
function requirePathList(value, what) {
|
|
666
|
+
if (!Array.isArray(value)) invalidDocument(`${what} must be an array of workspace paths`)
|
|
667
|
+
for (const item of value) {
|
|
668
|
+
if (typeof item !== 'string' || normalizePath(item).length === 0) invalidDocument(`${what} contains an invalid workspace path`)
|
|
669
|
+
}
|
|
670
|
+
}
|
|
671
|
+
|
|
672
|
+
/** Validate the settings switches. v3 allowed some switches to be absent. */
|
|
673
|
+
function validateSettings(raw, { requireAll }) {
|
|
674
|
+
requireObject(raw, 'settings')
|
|
675
|
+
for (const key of SETTING_KEYS) {
|
|
676
|
+
if (requireAll && !Object.hasOwn(raw, key)) invalidDocument(`settings.${key} is missing`)
|
|
677
|
+
optionalBoolean(raw[key], `settings.${key}`)
|
|
678
|
+
}
|
|
679
|
+
if (typeof raw.enabled !== 'boolean') invalidDocument('settings.enabled must be a boolean')
|
|
680
|
+
}
|
|
681
|
+
|
|
682
|
+
/** Validate the optional inheritance markers of a v4 skill member. */
|
|
683
|
+
function validateInheritance(raw, what) {
|
|
684
|
+
for (const key of ['modesFrom', 'workspacesFrom']) {
|
|
685
|
+
if (raw[key] !== undefined && raw[key] !== 'group' && raw[key] !== 'self') {
|
|
686
|
+
invalidDocument(`${what}.${key} must be 'group' or 'self'`)
|
|
687
|
+
}
|
|
688
|
+
}
|
|
689
|
+
}
|
|
690
|
+
|
|
691
|
+
/** Validate one stored MCP connection definition without echoing it. */
|
|
692
|
+
function validateDefinition(raw, what) {
|
|
693
|
+
requireObject(raw, what)
|
|
694
|
+
if (raw.transport !== undefined && !MCP_TRANSPORTS.includes(raw.transport)) invalidDocument(`${what}.transport is unsupported`)
|
|
695
|
+
for (const key of ['serverName', 'url', 'command', 'cwd']) optionalStringField(raw[key], `${what}.${key}`, 4096)
|
|
696
|
+
if (raw.args !== undefined) {
|
|
697
|
+
if (!Array.isArray(raw.args) || raw.args.some((arg) => typeof arg !== 'string')) {
|
|
698
|
+
invalidDocument(`${what}.args must be an array of strings`)
|
|
699
|
+
}
|
|
700
|
+
}
|
|
701
|
+
for (const key of ['headers', 'env']) {
|
|
702
|
+
if (raw[key] === undefined) continue
|
|
703
|
+
requireObject(raw[key], `${what}.${key}`)
|
|
704
|
+
for (const [name, value] of Object.entries(raw[key])) {
|
|
705
|
+
if (typeof name !== 'string' || name.length === 0 || name.length > 256 || typeof value !== 'string') {
|
|
706
|
+
invalidDocument(`${what}.${key} contains an invalid entry`)
|
|
707
|
+
}
|
|
708
|
+
}
|
|
709
|
+
}
|
|
710
|
+
}
|
|
711
|
+
|
|
712
|
+
/** Validate one pool member (`skills` / `mcp`). */
|
|
713
|
+
function validateMember(raw, what, { version, kind, sources }) {
|
|
714
|
+
requireObject(raw, what)
|
|
715
|
+
if (typeof raw.enabled !== 'boolean') invalidDocument(`${what}.enabled must be a boolean`)
|
|
716
|
+
requireNameList(raw.modes, `${what}.modes`)
|
|
717
|
+
requirePathList(raw.workspaces, `${what}.workspaces`)
|
|
718
|
+
optionalStringField(raw.installedAt, `${what}.installedAt`, 64)
|
|
719
|
+
if (version === STATE_VERSION) validateInheritance(raw, what)
|
|
720
|
+
if (kind === 'skill') {
|
|
721
|
+
optionalStringField(raw.sourceId, `${what}.sourceId`, 128)
|
|
722
|
+
optionalStringField(raw.digest, `${what}.digest`, 128)
|
|
723
|
+
if (
|
|
724
|
+
version === STATE_VERSION &&
|
|
725
|
+
typeof raw.sourceId === 'string' &&
|
|
726
|
+
raw.sourceId.length > 0 &&
|
|
727
|
+
isObject(sources) &&
|
|
728
|
+
!Object.hasOwn(sources, raw.sourceId) &&
|
|
729
|
+
(raw.modesFrom !== 'self' || raw.workspacesFrom !== 'self')
|
|
730
|
+
) {
|
|
731
|
+
invalidDocument(`${what}.sourceId references a missing source while its scope inherits; refusing to resolve the inheritance`)
|
|
732
|
+
}
|
|
733
|
+
}
|
|
734
|
+
if (kind === 'mcp') {
|
|
735
|
+
if (raw.definition !== undefined) validateDefinition(raw.definition, `${what}.definition`)
|
|
736
|
+
}
|
|
737
|
+
}
|
|
738
|
+
|
|
739
|
+
/** Validate one member map. */
|
|
740
|
+
function validateMembers(raw, what, options) {
|
|
741
|
+
requireObject(raw, what)
|
|
742
|
+
for (const [key, value] of Object.entries(raw)) {
|
|
743
|
+
if (cleanName(key) !== key) invalidDocument(`${what} contains an invalid member key`)
|
|
744
|
+
validateMember(value, `${what} member`, options)
|
|
745
|
+
}
|
|
746
|
+
}
|
|
747
|
+
|
|
748
|
+
/** Validate the optional `lastCheck` record of a Git source. */
|
|
749
|
+
function validateLastCheck(raw, what) {
|
|
750
|
+
requireObject(raw, what)
|
|
751
|
+
if (!CHECK_STATUSES.includes(raw.status)) invalidDocument(`${what}.status is unsupported`)
|
|
752
|
+
for (const key of ['at', 'remote', 'error']) optionalStringField(raw[key], `${what}.${key}`, 1024)
|
|
753
|
+
}
|
|
754
|
+
|
|
755
|
+
/** Validate one source record. */
|
|
756
|
+
function validateSource(raw, key, what) {
|
|
757
|
+
requireObject(raw, what)
|
|
758
|
+
if (typeof raw.id !== 'string' || cleanName(raw.id) !== raw.id || raw.id !== key) {
|
|
759
|
+
invalidDocument(`${what}.id must be a valid name matching its map key`)
|
|
760
|
+
}
|
|
761
|
+
if (!SOURCE_KINDS.includes(raw.kind)) invalidDocument(`${what}.kind is unsupported`)
|
|
762
|
+
optionalStringField(raw.label, `${what}.label`, 160)
|
|
763
|
+
if (raw.skills !== undefined) requireNameList(raw.skills, `${what}.skills`)
|
|
764
|
+
if (raw.excluded !== undefined) requireNameList(raw.excluded, `${what}.excluded`)
|
|
765
|
+
optionalStringField(raw.digest, `${what}.digest`, 128)
|
|
766
|
+
optionalStringField(raw.createdAt, `${what}.createdAt`, 64)
|
|
767
|
+
if (raw.kind !== 'git') return
|
|
768
|
+
if (deriveGit(raw) === null) invalidDocument(`${what} does not name a usable Git repository`)
|
|
769
|
+
if (raw.provider !== undefined && !GIT_PROVIDERS.includes(raw.provider)) invalidDocument(`${what}.provider is unsupported`)
|
|
770
|
+
for (const sub of ['url', 'project', 'branch', 'subdir', 'sha', 'tokenCredential']) {
|
|
771
|
+
optionalStringField(raw[sub], `${what}.${sub}`, 2048)
|
|
772
|
+
}
|
|
773
|
+
if (raw.lastCheck !== undefined) validateLastCheck(raw.lastCheck, `${what}.lastCheck`)
|
|
774
|
+
}
|
|
775
|
+
|
|
776
|
+
/** Validate the `sources` map. */
|
|
777
|
+
function validateSources(raw) {
|
|
778
|
+
requireObject(raw, 'sources')
|
|
779
|
+
for (const [key, value] of Object.entries(raw)) validateSource(value, key, 'sources entry')
|
|
780
|
+
}
|
|
781
|
+
|
|
782
|
+
/** Validate one group record (`repo:<project>` / `import:<sourceId>`). */
|
|
783
|
+
function validateGroup(raw, key, what) {
|
|
784
|
+
requireObject(raw, what)
|
|
785
|
+
if (raw.key !== undefined && raw.key !== key) invalidDocument(`${what}.key must match its map key`)
|
|
786
|
+
if (raw.kind !== undefined && !GROUP_KINDS.includes(raw.kind)) invalidDocument(`${what}.kind is unsupported`)
|
|
787
|
+
if (typeof raw.enabled !== 'boolean') invalidDocument(`${what}.enabled must be a boolean`)
|
|
788
|
+
requireNameList(raw.modes, `${what}.modes`)
|
|
789
|
+
requirePathList(raw.workspaces, `${what}.workspaces`)
|
|
790
|
+
if (
|
|
791
|
+
typeof key !== 'string' ||
|
|
792
|
+
key.length === 0 ||
|
|
793
|
+
key.length > 512 ||
|
|
794
|
+
/[\u0000-\u001f\u007f]/.test(key) ||
|
|
795
|
+
FORBIDDEN_GROUP_KEYS.has(key) ||
|
|
796
|
+
key in Object.prototype
|
|
797
|
+
) {
|
|
798
|
+
invalidDocument(`${what} has an invalid group key`)
|
|
799
|
+
}
|
|
800
|
+
const repoKey = key.startsWith('repo:')
|
|
801
|
+
const importKey = key.startsWith('import:')
|
|
802
|
+
if (repoKey && key.length <= 'repo:'.length) invalidDocument(`${what} has an invalid group key`)
|
|
803
|
+
if (importKey && key.length <= 'import:'.length) invalidDocument(`${what} has an invalid group key`)
|
|
804
|
+
if (raw.kind !== undefined && repoKey && raw.kind !== 'repo') invalidDocument(`${what}.kind does not match its key`)
|
|
805
|
+
if (raw.kind !== undefined && importKey && raw.kind !== 'import') invalidDocument(`${what}.kind does not match its key`)
|
|
806
|
+
}
|
|
807
|
+
|
|
808
|
+
/** Validate the `groups` map. */
|
|
809
|
+
function validateGroups(raw) {
|
|
810
|
+
requireObject(raw, 'groups')
|
|
811
|
+
for (const [key, value] of Object.entries(raw)) validateGroup(value, key, 'groups entry')
|
|
812
|
+
}
|
|
813
|
+
|
|
814
|
+
/**
|
|
815
|
+
* Validate a stored document before it is trusted for gating.
|
|
816
|
+
*
|
|
817
|
+
* `normalizeState` is deliberately lenient for pure migration/write helpers;
|
|
818
|
+
* reading a file is different: silently repairing a damaged document can widen
|
|
819
|
+
* what an Agent may reach. This function accepts exactly the complete v4 shape
|
|
820
|
+
* (and the v3 shape the explicit migration understands) and rejects anything it
|
|
821
|
+
* would otherwise have to invent, drop, or reinterpret.
|
|
822
|
+
*
|
|
823
|
+
* @param {unknown} raw - parsed JSON document.
|
|
824
|
+
* @returns {object} normalized v4 document.
|
|
825
|
+
* @throws {StateReadError} when the document is invalid or unsupported.
|
|
826
|
+
*/
|
|
827
|
+
export function normalizeReadableState(raw) {
|
|
828
|
+
if (!isObject(raw)) {
|
|
829
|
+
throw new StateReadError('resource-pool/state-not-object', 'state file is not a JSON object; refusing to overwrite or use it')
|
|
830
|
+
}
|
|
831
|
+
if (raw.version === LEGACY_VERSION) {
|
|
832
|
+
validateSettings(raw.settings, { requireAll: false })
|
|
833
|
+
if (raw.groups !== undefined) {
|
|
834
|
+
if (!isObject(raw.groups)) invalidDocument('v3 document has a non-object "groups" section')
|
|
835
|
+
if (Object.keys(raw.groups).length > 0) {
|
|
836
|
+
invalidDocument('v3 document contains v4-only groups; refusing to migrate away their scope')
|
|
837
|
+
}
|
|
838
|
+
}
|
|
839
|
+
for (const section of ['skills', 'mcp']) {
|
|
840
|
+
if (!isObject(raw[section])) continue
|
|
841
|
+
for (const member of Object.values(raw[section])) {
|
|
842
|
+
if (!isObject(member)) continue
|
|
843
|
+
if (member.modesFrom !== undefined || member.workspacesFrom !== undefined) {
|
|
844
|
+
invalidDocument('v3 document contains v4-only inheritance markers; refusing to reinterpret its scope')
|
|
845
|
+
}
|
|
846
|
+
}
|
|
847
|
+
}
|
|
848
|
+
validateSources(raw.sources)
|
|
849
|
+
validateMembers(raw.skills, 'skills', { version: LEGACY_VERSION, kind: 'skill', sources: raw.sources })
|
|
850
|
+
validateMembers(raw.mcp, 'mcp', { version: LEGACY_VERSION, kind: 'mcp', sources: raw.sources })
|
|
851
|
+
return normalizeState(migrateV3(raw))
|
|
852
|
+
}
|
|
853
|
+
if (raw.version !== STATE_VERSION) {
|
|
854
|
+
throw new StateReadError(
|
|
855
|
+
'resource-pool/state-unsupported-version',
|
|
856
|
+
'state file uses an unsupported version; refusing to overwrite or use it',
|
|
857
|
+
)
|
|
858
|
+
}
|
|
859
|
+
for (const section of STATE_SECTIONS) {
|
|
860
|
+
if (!isObject(raw[section])) invalidDocument(`missing or invalid "${section}" section`)
|
|
861
|
+
}
|
|
862
|
+
validateSettings(raw.settings, { requireAll: true })
|
|
863
|
+
validateSources(raw.sources)
|
|
864
|
+
validateGroups(raw.groups)
|
|
865
|
+
validateMembers(raw.skills, 'skills', { version: STATE_VERSION, kind: 'skill', sources: raw.sources })
|
|
866
|
+
validateMembers(raw.mcp, 'mcp', { version: STATE_VERSION, kind: 'mcp', sources: raw.sources })
|
|
867
|
+
return normalizeState(raw)
|
|
868
|
+
}
|
|
869
|
+
|
|
870
|
+
/**
|
|
871
|
+
* Validate the document an update mutator returned.
|
|
872
|
+
*
|
|
873
|
+
* `normalizeState` treats anything that is not a complete v4 document as an
|
|
874
|
+
* empty default, so persisting an accidental `undefined` result (a mutation
|
|
875
|
+
* that forgot to return, or an async mutator that resolved to nothing) — or a
|
|
876
|
+
* fragment such as `{version: 4}` — would silently erase every stored member
|
|
877
|
+
* and credential. Refuse anything incomplete before it can reach the file.
|
|
878
|
+
*
|
|
879
|
+
* @param {unknown} next - mutation result.
|
|
880
|
+
* @returns {object} the same document when it is acceptable.
|
|
881
|
+
* @throws {TypeError} when the result is not a complete v4 document.
|
|
882
|
+
*/
|
|
883
|
+
function assertStateDocument(next) {
|
|
884
|
+
if (!isObject(next) || next.version !== STATE_VERSION) {
|
|
885
|
+
throw new TypeError('StateStore.update(mutate) must return a complete v4 state document')
|
|
886
|
+
}
|
|
887
|
+
for (const section of STATE_SECTIONS) {
|
|
888
|
+
if (!isObject(next[section])) {
|
|
889
|
+
throw new TypeError(
|
|
890
|
+
`StateStore.update(mutate) must return a complete v4 state document: "${section}" must be an object`,
|
|
891
|
+
)
|
|
892
|
+
}
|
|
893
|
+
}
|
|
894
|
+
return next
|
|
895
|
+
}
|
|
896
|
+
|
|
589
897
|
/**
|
|
590
898
|
* Merge a settings patch over a normalized document.
|
|
591
899
|
* Unknown keys (including the retired `enforcePool`) are ignored.
|
|
@@ -720,46 +1028,204 @@ export function withoutExcluded(names, excluded) {
|
|
|
720
1028
|
export class StateStore {
|
|
721
1029
|
constructor({ file, logger, version = '0.3.0' } = {}) {
|
|
722
1030
|
this.file = typeof file === 'string' && file.length > 0 ? file : statePath()
|
|
1031
|
+
this.key = resolvePath(this.file)
|
|
723
1032
|
this.logger = logger
|
|
724
1033
|
this.version = version
|
|
725
1034
|
this.cached = undefined
|
|
726
1035
|
this.writeChain = Promise.resolve()
|
|
1036
|
+
// Marks the async context of a task currently running on `writeChain`, so a
|
|
1037
|
+
// nested write/update can be rejected instead of waiting on itself forever.
|
|
1038
|
+
this.taskContext = new AsyncLocalStorage()
|
|
1039
|
+
// Whether this Store instance has ever successfully read or written the
|
|
1040
|
+
// document. A later ENOENT is then a failure, not a fresh first run. A new
|
|
1041
|
+
// process cannot distinguish a deleted file from a genuine first run; that
|
|
1042
|
+
// boundary is documented in README/CONTRACTS.
|
|
1043
|
+
this.everLoaded = false
|
|
1044
|
+
// Whether the path was ever observed to exist (even if its bytes failed to
|
|
1045
|
+
// parse). Deleting it afterwards is still abnormal.
|
|
1046
|
+
this.everObserved = false
|
|
727
1047
|
}
|
|
728
1048
|
|
|
729
|
-
/**
|
|
1049
|
+
/**
|
|
1050
|
+
* Decode and validate one state text.
|
|
1051
|
+
*
|
|
1052
|
+
* @param {string} text - raw file contents.
|
|
1053
|
+
* @returns {object} normalized v4 document.
|
|
1054
|
+
* @throws {StateReadError} when the bytes are not a readable state document.
|
|
1055
|
+
*/
|
|
1056
|
+
#decode(text) {
|
|
1057
|
+
let raw
|
|
1058
|
+
try {
|
|
1059
|
+
raw = JSON.parse(text)
|
|
1060
|
+
} catch {
|
|
1061
|
+
throw new StateReadError('resource-pool/state-invalid-json', 'state file is not valid JSON; refusing to overwrite or use it')
|
|
1062
|
+
}
|
|
1063
|
+
const state = normalizeReadableState(raw)
|
|
1064
|
+
this.everLoaded = true
|
|
1065
|
+
return state
|
|
1066
|
+
}
|
|
1067
|
+
|
|
1068
|
+
/**
|
|
1069
|
+
* Read the document, caching the normalized result.
|
|
1070
|
+
*
|
|
1071
|
+
* A missing file is a valid first run only until this Store has seen the
|
|
1072
|
+
* document. Every other failure throws a {@link StateReadError}; returning
|
|
1073
|
+
* defaults here would silently widen the pool (an empty pool does not gate).
|
|
1074
|
+
*
|
|
1075
|
+
* @param {{fresh?: boolean}} [options] - force a disk read.
|
|
1076
|
+
* @returns {Promise<object>} normalized v4 document.
|
|
1077
|
+
* @throws {StateReadError} when the file is missing after a successful read,
|
|
1078
|
+
* unreadable, corrupt, unsupported or semantically invalid.
|
|
1079
|
+
*/
|
|
730
1080
|
async read({ fresh = false } = {}) {
|
|
731
1081
|
if (!fresh && this.cached !== undefined) return this.cached
|
|
732
|
-
let
|
|
1082
|
+
let text
|
|
733
1083
|
try {
|
|
734
|
-
|
|
1084
|
+
text = await readFile(this.file, 'utf8')
|
|
735
1085
|
} catch (error) {
|
|
736
|
-
if (error?.code !== 'ENOENT')
|
|
737
|
-
|
|
1086
|
+
if (error?.code !== 'ENOENT') {
|
|
1087
|
+
this.everObserved = true
|
|
1088
|
+
observedStateFiles.add(this.key)
|
|
1089
|
+
throw new StateReadError('resource-pool/state-unreadable', 'state file could not be read; refusing to overwrite or use it')
|
|
1090
|
+
}
|
|
1091
|
+
if (this.everLoaded || this.everObserved || observedStateFiles.has(this.key)) {
|
|
1092
|
+
throw new StateReadError(
|
|
1093
|
+
'resource-pool/state-missing',
|
|
1094
|
+
'state file disappeared after it was known to exist; refusing to treat it as a first run',
|
|
1095
|
+
)
|
|
1096
|
+
}
|
|
1097
|
+
this.cached = defaultState()
|
|
1098
|
+
return this.cached
|
|
738
1099
|
}
|
|
739
|
-
this.
|
|
1100
|
+
this.everObserved = true
|
|
1101
|
+
observedStateFiles.add(this.key)
|
|
1102
|
+
this.cached = this.#decode(text)
|
|
740
1103
|
return this.cached
|
|
741
1104
|
}
|
|
742
1105
|
|
|
743
|
-
/**
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
1106
|
+
/**
|
|
1107
|
+
* Queue one operation behind every write/update already scheduled.
|
|
1108
|
+
*
|
|
1109
|
+
* A rejection settles only the operation's own promise: the queue itself is
|
|
1110
|
+
* reset to a fulfilled promise, so one failed save never wedges later ones.
|
|
1111
|
+
*
|
|
1112
|
+
* A call made from inside a queued task's async context (typically `await
|
|
1113
|
+
* store.write(...)` inside an `update` mutator) is rejected immediately: it
|
|
1114
|
+
* would queue behind the very task awaiting it and deadlock the store.
|
|
1115
|
+
* AsyncLocalStorage distinguishes those descendants from independent callers
|
|
1116
|
+
* that merely arrive while the queue is busy — a process-wide "busy" flag
|
|
1117
|
+
* would wrongly reject those external calls too.
|
|
1118
|
+
*
|
|
1119
|
+
* @param {() => Promise<object>} task - operation to run once its turn comes.
|
|
1120
|
+
* @returns {Promise<object>} the operation's result.
|
|
1121
|
+
*/
|
|
1122
|
+
#enqueue(task) {
|
|
1123
|
+
if (this.taskContext.getStore() === true) {
|
|
1124
|
+
return Promise.reject(
|
|
1125
|
+
new Error(
|
|
1126
|
+
'StateStore.write/update cannot be called from inside an update mutator: it would wait on the same queue',
|
|
1127
|
+
),
|
|
1128
|
+
)
|
|
1129
|
+
}
|
|
1130
|
+
const run = this.writeChain.then(() => this.taskContext.run(true, task))
|
|
1131
|
+
this.writeChain = run.then(
|
|
1132
|
+
() => undefined,
|
|
1133
|
+
() => undefined,
|
|
1134
|
+
)
|
|
757
1135
|
return run
|
|
758
1136
|
}
|
|
759
1137
|
|
|
760
|
-
/**
|
|
1138
|
+
/**
|
|
1139
|
+
* Read the document for a queued read-modify-write, failing instead of
|
|
1140
|
+
* guessing.
|
|
1141
|
+
*
|
|
1142
|
+
* An update is about to overwrite the file, so it uses the same fail-closed
|
|
1143
|
+
* validation as `read()`: a JSON parse error, unsupported version, semantic
|
|
1144
|
+
* invalidity or I/O error must abort the save instead of replacing
|
|
1145
|
+
* credential-bearing state with defaults. Only a missing file (ENOENT)
|
|
1146
|
+
* legitimately starts from defaults, and only before this store has observed
|
|
1147
|
+
* the document.
|
|
1148
|
+
*
|
|
1149
|
+
* @returns {Promise<object>} normalized on-disk document.
|
|
1150
|
+
*/
|
|
1151
|
+
async #readStrict() {
|
|
1152
|
+
let text
|
|
1153
|
+
try {
|
|
1154
|
+
text = await readFile(this.file, 'utf8')
|
|
1155
|
+
} catch (error) {
|
|
1156
|
+
if (error?.code === 'ENOENT') {
|
|
1157
|
+
if (this.everLoaded || this.everObserved || observedStateFiles.has(this.key)) {
|
|
1158
|
+
throw new StateReadError(
|
|
1159
|
+
'resource-pool/state-missing',
|
|
1160
|
+
'state file disappeared after it was known to exist; refusing to overwrite it',
|
|
1161
|
+
)
|
|
1162
|
+
}
|
|
1163
|
+
this.cached = defaultState()
|
|
1164
|
+
return this.cached
|
|
1165
|
+
}
|
|
1166
|
+
this.everObserved = true
|
|
1167
|
+
observedStateFiles.add(this.key)
|
|
1168
|
+
throw new StateReadError('resource-pool/state-unreadable', 'state file could not be read; refusing to overwrite it')
|
|
1169
|
+
}
|
|
1170
|
+
this.everObserved = true
|
|
1171
|
+
observedStateFiles.add(this.key)
|
|
1172
|
+
this.cached = this.#decode(text)
|
|
1173
|
+
return this.cached
|
|
1174
|
+
}
|
|
1175
|
+
|
|
1176
|
+
/**
|
|
1177
|
+
* Persist one normalized document atomically, then update the cache.
|
|
1178
|
+
*
|
|
1179
|
+
* Only the queue may call this: `write`/`update` enqueue, so calling them from
|
|
1180
|
+
* inside a queued task would wait on itself and deadlock.
|
|
1181
|
+
*
|
|
1182
|
+
* @param {object} normalized - normalized document.
|
|
1183
|
+
* @returns {Promise<object>} the persisted document.
|
|
1184
|
+
*/
|
|
1185
|
+
async #persist(normalized) {
|
|
1186
|
+
await mkdir(dirname(this.file), { recursive: true })
|
|
1187
|
+
const temporary = `${this.file}.${process.pid}.${Date.now()}.tmp`
|
|
1188
|
+
// 0600: an MCP member may carry an `Authorization` header, so the pool
|
|
1189
|
+
// document holds the same secrets a profile patch would.
|
|
1190
|
+
await writeFile(temporary, `${JSON.stringify(normalized, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
|
|
1191
|
+
await rename(temporary, this.file)
|
|
1192
|
+
this.cached = normalized
|
|
1193
|
+
this.everLoaded = true
|
|
1194
|
+
this.everObserved = true
|
|
1195
|
+
observedStateFiles.add(this.key)
|
|
1196
|
+
return normalized
|
|
1197
|
+
}
|
|
1198
|
+
|
|
1199
|
+
/** Persist a complete, readable document, queued behind earlier writes/updates. */
|
|
1200
|
+
async write(state) {
|
|
1201
|
+
// Validate before queueing: a direct write must not be able to replace a
|
|
1202
|
+
// credential-bearing document with a fragment or a semantically broken one.
|
|
1203
|
+
const normalized = normalizeReadableState(state)
|
|
1204
|
+
return this.#enqueue(() => this.#persist(normalized))
|
|
1205
|
+
}
|
|
1206
|
+
|
|
1207
|
+
/**
|
|
1208
|
+
* Apply one mutation to a fresh read and persist the result as one queued
|
|
1209
|
+
* read-modify-write.
|
|
1210
|
+
*
|
|
1211
|
+
* The strict fresh read happens inside the queue, after every earlier
|
|
1212
|
+
* write/update has settled. Two concurrent updates therefore see each other's
|
|
1213
|
+
* result instead of overwriting it, and direct `write` calls keep their call
|
|
1214
|
+
* order. `mutate` may be async, but must resolve to a complete v4 document;
|
|
1215
|
+
* an invalid result is rejected before anything is written. A nested
|
|
1216
|
+
* `store.write`/`store.update` inside `mutate` is rejected instead of
|
|
1217
|
+
* enqueueing behind itself, which would deadlock the queue.
|
|
1218
|
+
*
|
|
1219
|
+
* @param {(state: object) => object|Promise<object>} mutate - pure mutation.
|
|
1220
|
+
* @returns {Promise<object>} the persisted document.
|
|
1221
|
+
*/
|
|
761
1222
|
async update(mutate) {
|
|
762
|
-
|
|
763
|
-
|
|
1223
|
+
return this.#enqueue(async () => {
|
|
1224
|
+
const current = await this.#readStrict()
|
|
1225
|
+
const next = assertStateDocument(await mutate(current))
|
|
1226
|
+
// Validate the mutation's result with the same fail-closed rules as a
|
|
1227
|
+
// disk read: never persist a document we would refuse to read back.
|
|
1228
|
+
return this.#persist(normalizeReadableState(next))
|
|
1229
|
+
})
|
|
764
1230
|
}
|
|
765
1231
|
}
|