pm-ops 2026.10.21 → 2026.10.24
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 +34 -0
- package/README.md +247 -5
- package/dist/backend-capabilities.d.ts +83 -0
- package/dist/backend-capabilities.d.ts.map +1 -0
- package/dist/backend-capabilities.js +255 -0
- package/dist/backend-capabilities.js.map +1 -0
- package/dist/diagnostic-plans.d.ts +88 -0
- package/dist/diagnostic-plans.d.ts.map +1 -0
- package/dist/diagnostic-plans.js +178 -0
- package/dist/diagnostic-plans.js.map +1 -0
- package/dist/diagnostic-probes.d.ts +4 -0
- package/dist/diagnostic-probes.d.ts.map +1 -0
- package/dist/diagnostic-probes.js +104 -0
- package/dist/diagnostic-probes.js.map +1 -0
- package/dist/evidence-expiry.d.ts +101 -0
- package/dist/evidence-expiry.d.ts.map +1 -0
- package/dist/evidence-expiry.js +194 -0
- package/dist/evidence-expiry.js.map +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +77 -12
- package/dist/index.js.map +1 -1
- package/manifest.json +1 -1
- package/package.json +15 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,39 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 2026.10.23 - 2026-10-23
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- Freeze the merge-driver launcher and accept every released launcher revision ([ops-m82r](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/features/ops-m82r.toon))
|
|
8
|
+
- One reusable daily release workflow for fleet packages ([ops-reusable-daily-release](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/features/ops-reusable-daily-release.toon))
|
|
9
|
+
|
|
10
|
+
### Changed
|
|
11
|
+
|
|
12
|
+
- Enable the gated pm-github issue sync and remove the braces chain ([ops-gated-issue-sync](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/chores/ops-gated-issue-sync.toon))
|
|
13
|
+
- Adopt pm-github 2026.10.16: default-branch-safe gated sync and daily gated closeout PRs ([ops-l7gb](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/chores/ops-l7gb.toon))
|
|
14
|
+
|
|
15
|
+
### Fixed
|
|
16
|
+
|
|
17
|
+
- A release run bumped and committed a new version every night while publishing was impossible, because the only externally-failable step runs last ([ops-e9g6](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-e9g6.toon))
|
|
18
|
+
- Fix release publish-before-protected-main-push ordering ([ops-gitr](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-gitr.toon))
|
|
19
|
+
- A parenthesised command inside a case arm is read as an arm label, refusing a publish the shell attests ([ops-vkvy](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-vkvy.toon))
|
|
20
|
+
- Self-hosted pm-changelog is reported not ready because it does not depend on itself ([ops-pksh](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-pksh.toon))
|
|
21
|
+
- Adding a source file breaks the coverage gate in three places, and none of them says so ([ops-cl0o](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-cl0o.toon))
|
|
22
|
+
- Recognize third-party publish wrappers (semantic-release, np, release-it, lerna publish, changeset publish) in the canonical attestation auditor ([ops-third-party-publish-wrappers](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-third-party-publish-wrappers.toon))
|
|
23
|
+
- A hardcoded fixture date aged out of the seven day window and broke the daily release ([ops-i2iz](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-i2iz.toon))
|
|
24
|
+
- The release completeness audit reported a published version and its GitHub Release as missing, turning a successful release into a failed one ([ops-fcow](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-fcow.toon))
|
|
25
|
+
- Guarded merge-driver launcher: omit-dev clone installs complete instead of failing on the devDependency import ([ops-mqdi](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-mqdi.toon))
|
|
26
|
+
- Duplication gate scans generated PM extension copies ([ops-to4t](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-to4t.toon))
|
|
27
|
+
- ops verify-release times out on real full package gate after five minutes ([ops-3xyb](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-3xyb.toon))
|
|
28
|
+
- Preserve launcher resolution errors when presence probes fail ([ops-85at](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-85at.toon))
|
|
29
|
+
- Keep multi-line quoted strings open in the publish-attestation scanner ([ops-attestation-multiline-quotes](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-attestation-multiline-quotes.toon))
|
|
30
|
+
- The release job authenticated with a stored npm token that expired, so publishing stopped while every other gate stayed green ([ops-cenj](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-cenj.toon))
|
|
31
|
+
|
|
32
|
+
### Other
|
|
33
|
+
|
|
34
|
+
- Enable GitHub CodeQL code scanning ([ops-jasw](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/chores/ops-jasw.toon))
|
|
35
|
+
- Characterize pre-existing fleet workflow scanner refusals ([ops-0u7l](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/tasks/ops-0u7l.toon))
|
|
36
|
+
|
|
3
37
|
## 2026.10.15 - 2026-10-15
|
|
4
38
|
|
|
5
39
|
### Security
|
package/README.md
CHANGED
|
@@ -10,15 +10,32 @@ Multi-repo fleet operations for [pm-cli](https://github.com/unbraind/pm-cli).
|
|
|
10
10
|
|
|
11
11
|
## Installation
|
|
12
12
|
|
|
13
|
+
Use the published package so npm installs its runtime dependencies before activation.
|
|
14
|
+
In a plain project directory (no git repository required), initialize a tracker and
|
|
15
|
+
activate the pinned registry release:
|
|
16
|
+
|
|
13
17
|
```bash
|
|
14
|
-
|
|
18
|
+
npx -y @unbrained/pm-cli@2026.10.21 init --defaults --agent-guidance skip
|
|
19
|
+
npx -y @unbrained/pm-cli@2026.10.21 install npm:pm-ops@2026.10.21 --project
|
|
15
20
|
```
|
|
16
21
|
|
|
17
|
-
|
|
22
|
+
With Bun, use `bunx` instead of `npx -y` for both commands.
|
|
23
|
+
The explicit `npm:` source selects the registry package.
|
|
18
24
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
25
|
+
GitHub-source activation alone does not install this package's runtime dependencies.
|
|
26
|
+
It requires built `dist/` output and all `package.json` runtime dependencies
|
|
27
|
+
(including `@toon-format/toon`, `typescript` and `yaml`) resolvable from the
|
|
28
|
+
activated module graph, plus the pm CLI peer. A fresh source-only project lacks
|
|
29
|
+
those dependencies and activation fails. Use the registry route above for fresh
|
|
30
|
+
projects; a source checkout needs dependency installation and a build before local
|
|
31
|
+
activation.
|
|
32
|
+
|
|
33
|
+
### Without git
|
|
34
|
+
|
|
35
|
+
Tracker metrics, policy checks and file-based reports work in plain directories.
|
|
36
|
+
GitHub probes, release inventory/repair and changelog generation from tags need a
|
|
37
|
+
git repository and their provider tools. Git-only checks do not certify a plain
|
|
38
|
+
tracker as a release checkout.
|
|
22
39
|
|
|
23
40
|
---
|
|
24
41
|
|
|
@@ -545,3 +562,228 @@ boundary is documented in [the auditor docs](docs/canonical-publication-regressi
|
|
|
545
562
|
to preserve actual shell semantics; `test/pack-prepare.test.ts` compares real Git
|
|
546
563
|
config bytes around npm pack and checks install/ci registration. Artifact-time
|
|
547
564
|
refusal does not bypass broken-package guards during installation.
|
|
565
|
+
|
|
566
|
+
## Backend capability assurance
|
|
567
|
+
|
|
568
|
+
`pm ops capabilities` audits the current tracker without changing it. Use
|
|
569
|
+
`pm ops capabilities --config docs/examples/backend-capabilities.json --json`
|
|
570
|
+
for the [example configuration](docs/examples/backend-capabilities.json).
|
|
571
|
+
The default audit uses the host-resolved tracker, including `--pm-path` and
|
|
572
|
+
`PM_PATH` selections, independently of the working directory.
|
|
573
|
+
The default output is compact TOON; `--json` returns the same typed matrix.
|
|
574
|
+
There are three rows per configured adapter, capped at 32 adapters in a config.
|
|
575
|
+
Reports contain public adapter labels, counts and remedies, with no item data,
|
|
576
|
+
connection strings, exception messages or local paths.
|
|
577
|
+
|
|
578
|
+
The audited SDK read contracts are `list` (complete, count-consistent, unique
|
|
579
|
+
nonempty item IDs), `get` (one deterministic list ID returned unchanged), and
|
|
580
|
+
`schema` (nonempty, unique type names). `checked` records the number of list
|
|
581
|
+
items, get probes or schema types actually checked. An empty or unavailable
|
|
582
|
+
list leaves get `unverified`; the diagnostic never creates a probe item.
|
|
583
|
+
This is read-contract assurance, not write, concurrency, recovery or native
|
|
584
|
+
SQL/MCP protocol certification. Directory reads use a disposable snapshot of
|
|
585
|
+
settings and registered item folders, containing SDK cache writes away from
|
|
586
|
+
the original tracker. Audit a stable read-only copy for reproducible results.
|
|
587
|
+
Symlinked inputs are refused. Snapshot cleanup restores directory permissions
|
|
588
|
+
before enumeration and attempts removal even after a permission error. Cleanup
|
|
589
|
+
errors do not replace the audit evidence.
|
|
590
|
+
|
|
591
|
+
| Status | Meaning |
|
|
592
|
+
| --- | --- |
|
|
593
|
+
| `supported` | Declared operation passed its invariant |
|
|
594
|
+
| `unsupported` | Adapter does not declare the operation; no call was made |
|
|
595
|
+
| `unavailable` | Connection, read permission or transport failed |
|
|
596
|
+
| `invariant_failed` | Read completed with invalid evidence, or unsafe snapshot input |
|
|
597
|
+
| `unverified` | No list ID is available to test get safely |
|
|
598
|
+
|
|
599
|
+
Each refusal has a stable `backend_<status>` code and a remedy. `ok` means
|
|
600
|
+
all **declared** operations verified; inspect `counts.unsupported` when requiring
|
|
601
|
+
full read coverage. The CLI returns the report even on failed probes, so agents
|
|
602
|
+
must inspect `ok` and the per-operation statuses.
|
|
603
|
+
|
|
604
|
+
For database and MCP backends, configure `kind`, `id`, `operations` and an
|
|
605
|
+
`endpoint` pointing to an operator-controlled **read-only HTTP bridge**. The
|
|
606
|
+
bridge translates the backend's SDK reads to the normalized contract below;
|
|
607
|
+
it is not a database DSN or a native MCP endpoint. The diagnostic sends GET
|
|
608
|
+
requests only, with a five-second timeout and redirects disabled. Keep bridge
|
|
609
|
+
credentials in its deployment; URL userinfo is rejected. Never configure a
|
|
610
|
+
GET endpoint with side effects.
|
|
611
|
+
|
|
612
|
+
```json
|
|
613
|
+
[{"id":"database","kind":"database","endpoint":"https://bridge.example/reads","operations":["list","get","schema"]}]
|
|
614
|
+
```
|
|
615
|
+
|
|
616
|
+
The bridge receives `?operation=list`, `?operation=get&id=<selected-id>` or
|
|
617
|
+
`?operation=schema` (existing query parameters are preserved), returning JSON:
|
|
618
|
+
|
|
619
|
+
```json
|
|
620
|
+
{"items":[{"id":"sample-1"}],"count":1,"complete":true}
|
|
621
|
+
{"id":"sample-1"}
|
|
622
|
+
{"types":["Task"]}
|
|
623
|
+
```
|
|
624
|
+
|
|
625
|
+
SDK consumers can supply their own database/MCP read ports without HTTP:
|
|
626
|
+
|
|
627
|
+
```ts
|
|
628
|
+
import { auditBackendCapabilities, type BackendReadAdapter } from "pm-ops/backend-capabilities";
|
|
629
|
+
|
|
630
|
+
// Bind side-effect-free reads only. Return the normalized contract above;
|
|
631
|
+
// throw BackendReadRefusal for known transport/integrity failures.
|
|
632
|
+
declare const adapters: readonly BackendReadAdapter[];
|
|
633
|
+
const matrix = await auditBackendCapabilities(adapters);
|
|
634
|
+
console.log(matrix.counts);
|
|
635
|
+
```
|
|
636
|
+
|
|
637
|
+
`auditConfiguredBackends` and `auditBackendConfigFile` expose the same directory
|
|
638
|
+
snapshot and HTTP bridge bindings used by the CLI. Config roots resolve relative
|
|
639
|
+
to the config file. Command/schema discovery in core, pm-web's database doctor,
|
|
640
|
+
and Cargo package readiness are separate checks.
|
|
641
|
+
|
|
642
|
+
## Without git
|
|
643
|
+
|
|
644
|
+
Evidence expiry, backend capability diagnostics, scan, policy, status, outdated, audit, metrics,
|
|
645
|
+
reports and docstring analysis work in plain directories. The capability and
|
|
646
|
+
evidence expiry paths never invoke Git. Release verification runs package-defined
|
|
647
|
+
scripts, which may
|
|
648
|
+
need Git; GitHub queries need their own credentials and network access. Configure
|
|
649
|
+
and validate those requirements separately.
|
|
650
|
+
|
|
651
|
+
## Operational evidence expiry
|
|
652
|
+
|
|
653
|
+
`pm ops evidence-expiry` checks whether retained health, coverage and recovery
|
|
654
|
+
claims still have reusable evidence. Core assurance owns the contracts and their
|
|
655
|
+
immutable verdicts; this policy attaches a maximum age, required core population
|
|
656
|
+
scope and captured package/backend identities to an exact assertion receipt.
|
|
657
|
+
It does not run health checks, measure coverage, perform restores or replace
|
|
658
|
+
pm-review's exact-head review gate.
|
|
659
|
+
|
|
660
|
+
```bash
|
|
661
|
+
pm ops evidence-expiry --policy docs/examples/evidence-policy.json --versions docs/examples/evidence-versions.json
|
|
662
|
+
pm ops evidence-expiry --policy docs/examples/evidence-policy.json --versions docs/examples/evidence-versions.json --now 2026-10-22T10:01:00.000Z --limit 20 --json
|
|
663
|
+
```
|
|
664
|
+
|
|
665
|
+
The [example policy](docs/examples/evidence-policy.json) binds three independent
|
|
666
|
+
claims. With matching accepted receipts, the [current versions](docs/examples/evidence-versions.json)
|
|
667
|
+
change `backend:directory` from `v1` to `v2`: tracker health needs revalidation;
|
|
668
|
+
coverage and recovery stay fresh. Changing `package:consumer` affects health and
|
|
669
|
+
coverage, while changing `backend:recovery` affects only the restore drill.
|
|
670
|
+
The examples contain illustrative receipt selectors: without those actual
|
|
671
|
+
recorded receipts, all three claims report `evidence_missing`.
|
|
672
|
+
|
|
673
|
+
Capture the `receipt` selector (`gate_id`, `tree_id`, `evaluated_at`,
|
|
674
|
+
`assertion_id`) from a core `pm assurance verdicts` result. Capture `versions`
|
|
675
|
+
**when accepting the evidence**, separately from the current version inventory.
|
|
676
|
+
Include every relevant package, backend, configuration revision or deployment
|
|
677
|
+
identity; omitted dependencies cannot trigger invalidation. Versions compare as
|
|
678
|
+
exact strings, including upgrades, downgrades and backend replacements. Use
|
|
679
|
+
public identity labels rather than endpoints or credentials. `scope` uses core
|
|
680
|
+
`all`, `active`, or `filter` with `measurement_id`. A scope label does not prove
|
|
681
|
+
that a measurement actually exercises a health check or restore: the consumer's
|
|
682
|
+
core contracts and evidence collection must establish that meaning.
|
|
683
|
+
|
|
684
|
+
A receipt must be durable, complete, unambiguous and non-dry-run, with a passing
|
|
685
|
+
named assertion, proven negative controls and a positive population. Other
|
|
686
|
+
assertions in its gate are judged independently. The required scope must match.
|
|
687
|
+
Evidence expires **at** `evaluated_at + max_age_seconds`; future evidence needs
|
|
688
|
+
revalidation. A missing current version, missing receipt or unreadable/unsealed
|
|
689
|
+
history remains `unavailable`, never fresh. The audit checks core record hashes
|
|
690
|
+
and refuses history changes during its read; this detects corruption, not a
|
|
691
|
+
malicious writer authorized to replace and reseal the entire tracker. It never
|
|
692
|
+
rewrites evidence or refreshes timestamps. Only the newest 1000 durable verdicts
|
|
693
|
+
are searched; collect new evidence if a receipt has fallen out of that window.
|
|
694
|
+
|
|
695
|
+
Default output is compact TOON; the host's `--json` selects JSON. `ok` is the
|
|
696
|
+
**authoritative diagnostic predicate**; like `ops capabilities`, a completed
|
|
697
|
+
diagnostic returns normally even when claims need attention. Malformed inputs
|
|
698
|
+
throw `EvidenceExpiryRefusal` with `code`, `remedy` and nonzero `exitCode`.
|
|
699
|
+
Counts cover every claim, actionable rows precede fresh rows, and `omitted`
|
|
700
|
+
reports rows beyond `--limit` (default 20, maximum 1000). Each row carries a typed
|
|
701
|
+
`code`, affected identity keys, expiration time and remedy; raw tracker content
|
|
702
|
+
and version values are excluded. Requirements use this precedence: availability,
|
|
703
|
+
acceptance, scope, missing versions, future time, changed versions, expiry.
|
|
704
|
+
Resolve the first refusal and rerun to reveal any remaining requirement.
|
|
705
|
+
|
|
706
|
+
```ts
|
|
707
|
+
import { auditEvidenceExpiry, evaluateEvidenceExpiry,
|
|
708
|
+
parseEvidenceExpiryPolicy, parseEvidenceVersions } from "pm-ops/evidence-expiry";
|
|
709
|
+
|
|
710
|
+
const policy = parseEvidenceExpiryPolicy(policyJson);
|
|
711
|
+
const current = parseEvidenceVersions(currentVersionJson);
|
|
712
|
+
const report = await auditEvidenceExpiry(trackerRoot, policy, current);
|
|
713
|
+
// Database/MCP hosts can supply their own authenticated durable core receipts.
|
|
714
|
+
const remoteReport = evaluateEvidenceExpiry(policy, current, durableReceipts);
|
|
715
|
+
// Pass null if evidence cannot be read; an empty array means no matching receipts.
|
|
716
|
+
```
|
|
717
|
+
|
|
718
|
+
The SDK exposes typed policies, claims, reports, rows, statuses and refusal codes.
|
|
719
|
+
JSON readers validate 1-1000 unique claims, canonical UTC timestamps, positive
|
|
720
|
+
integer ages up to ten years, and at most 100 identities per version map. The
|
|
721
|
+
read-only directory audit uses core SDK history, assurance and integrity APIs;
|
|
722
|
+
backend-neutral evaluation performs no I/O and trusts the caller to authenticate
|
|
723
|
+
its supplied receipts. Neither entrypoint changes assurance declarations or
|
|
724
|
+
stores a second copy of the verdict history.
|
|
725
|
+
|
|
726
|
+
### Bounded diagnostic plans
|
|
727
|
+
|
|
728
|
+
`pm ops diagnose` turns **observed failure codes** into an ordered, reviewable
|
|
729
|
+
read-only plan. Pass the classifications found during your scan/report investigation;
|
|
730
|
+
it does not rerun scan or invent failures. Core `pm plan` remains the owner of stored
|
|
731
|
+
steps and approvals; this command adds bounded diagnostic execution, with no scheduler.
|
|
732
|
+
|
|
733
|
+
```bash
|
|
734
|
+
pm ops diagnose --failures items_unreadable,history_invalid --processes 2 --network 0 --time-ms 10000 --json > diagnostic-plan.json
|
|
735
|
+
# Review the commands, scope, budget and id in diagnostic-plan.json.
|
|
736
|
+
pm ops diagnose --plan diagnostic-plan.json --select <reviewed-id> --json
|
|
737
|
+
# Omit --json for compact native TOON.
|
|
738
|
+
```
|
|
739
|
+
|
|
740
|
+
Generation does not execute probes. Execution requires the exact reviewed id and
|
|
741
|
+
original canonical tracker directory. A changed budget, step, order or scope requires
|
|
742
|
+
a new plan and selection. Plans deduplicate observations into the following catalog
|
|
743
|
+
order, with versioned command identities retained in every receipt and repeat run:
|
|
744
|
+
|
|
745
|
+
| Observed failure | Command identity | Read performed | Network reservation |
|
|
746
|
+
| --- | --- | --- | --- |
|
|
747
|
+
| `schema_unreadable` | `sdk:schema:v1` | Core settings and registered schema type count | 0 |
|
|
748
|
+
| `items_unreadable` | `sdk:items:v1` | Registered source item files through the canonical SDK document reader | 0 |
|
|
749
|
+
| `history_invalid` | `sdk:history:v1` | Core per-item history snapshot and verification against each current document | 0 |
|
|
750
|
+
| `registry_unavailable` | `http:registry-head:v1` | One HEAD to `https://registry.npmjs.org/`, redirects refused | 1 |
|
|
751
|
+
|
|
752
|
+
Default ceilings are **3 child launches, 0 HTTP requests and 10000 ms total**.
|
|
753
|
+
Allowed ranges are processes 0–4, network 0–1 and time 1–60000 ms. Reservations
|
|
754
|
+
are charged before dispatch, including failed launches. Network units are logical
|
|
755
|
+
HTTP requests, not DNS packets or transport retransmissions. The shared monotonic
|
|
756
|
+
deadline includes process startup; each worker is killed at its remaining deadline.
|
|
757
|
+
Termination and cleanup can add a small amount to measured elapsed time after the
|
|
758
|
+
deadline; no further probe is dispatched. Each worker has a 128 MiB V8 heap limit and a 4 KiB output ceiling. No arbitrary
|
|
759
|
+
command, shell, endpoint, executable, environment options or extension hooks run.
|
|
760
|
+
After any exhausted ceiling, **all later probes remain skipped**, with their original
|
|
761
|
+
command identities and a typed remedy. Probe failures may continue within budget.
|
|
762
|
+
|
|
763
|
+
Receipts return only fixed command identities, counts, codes and remedies. Tracker
|
|
764
|
+
text, identifiers, paths, URLs from failures, credentials, child stderr and raw errors
|
|
765
|
+
are never included. A SHA-256 directory binding identifies scope without printing its
|
|
766
|
+
path; it is an identity binding, not an encryption or authentication mechanism. Settings and optional schemas hydrate only in a parent-owned disposable copy,
|
|
767
|
+
which is removed even when a worker times out. Source item files are read directly
|
|
768
|
+
without SDK cache writes. Malformed settings and schema warnings fail closed. Links and ambiguous item identities
|
|
769
|
+
are refused. Each probe observes the tracker when it runs; these diagnostics do not
|
|
770
|
+
assert a transactionally consistent snapshot across concurrent writers. History checks
|
|
771
|
+
cover item streams, not workspace assurance or recovery. Empty item populations return
|
|
772
|
+
zero checked and do not establish nonempty acceptance evidence.
|
|
773
|
+
|
|
774
|
+
The diagnostic predicate is `result.ok`: a completed report returns normally even
|
|
775
|
+
when a budget stops probes or a probe fails. Invalid inputs throw `DiagnosticRefusal`
|
|
776
|
+
with `code`, `remedy` and exit code 2 (`invalid_options`, `invalid_plan`,
|
|
777
|
+
`selection_required`, `scope_unavailable`, `scope_mismatch`). Files must be version 1
|
|
778
|
+
JSON review artifacts no larger than 16 KiB. Execution flags cannot override a reviewed
|
|
779
|
+
artifact. Defaults produce at most four rows in native TOON or JSON.
|
|
780
|
+
|
|
781
|
+
The typed SDK exports `createDiagnosticPlan`, `parseDiagnosticPlan`,
|
|
782
|
+
`readDiagnosticPlan`, `executeDiagnosticPlan`, and `DiagnosticRefusal` from
|
|
783
|
+
`pm-ops/diagnostic-plans`. See [the SDK example](docs/diagnostic-plans.md).
|
|
784
|
+
|
|
785
|
+
Diagnostic generation and execution work **without git**, including when Git is
|
|
786
|
+
absent from PATH, for an ordinary directory tracker. They never invoke Git or mutate
|
|
787
|
+
the tracker. Public HTTP diagnostics require explicit network budget. Database and
|
|
788
|
+
MCP diagnostics remain the separate backend read-bridge capability command; directory
|
|
789
|
+
plans do not claim to execute against those backends.
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
/** Fixed audited read surface. Mutations are deliberately outside this contract. */
|
|
2
|
+
export declare const BACKEND_OPERATIONS: readonly ["list", "get", "schema"];
|
|
3
|
+
/** One audited SDK read operation. */
|
|
4
|
+
export type BackendOperation = typeof BACKEND_OPERATIONS[number];
|
|
5
|
+
/** Outcome distinguishes lack of support, transport failure and broken evidence. */
|
|
6
|
+
export type BackendCapabilityStatus = "supported" | "unsupported" | "unavailable" | "invariant_failed" | "unverified";
|
|
7
|
+
/** A provider must expose only side-effect-free reads; results cross an untrusted boundary. */
|
|
8
|
+
export interface BackendReadAdapter {
|
|
9
|
+
/** Public, non-sensitive adapter label. */
|
|
10
|
+
id: string;
|
|
11
|
+
/** Storage implementation category, independent of transport. */
|
|
12
|
+
kind: "directory" | "database" | "mcp";
|
|
13
|
+
/** Declared support; missing operations are never invoked. */
|
|
14
|
+
operations: readonly BackendOperation[];
|
|
15
|
+
/** Execute a normalized read: list -> {items:[{id}],count,complete}; get -> {id}; schema -> {types:[string]}. */
|
|
16
|
+
read: (operation: BackendOperation, id?: string) => Promise<unknown>;
|
|
17
|
+
}
|
|
18
|
+
/** Typed refusal with a safe remedy; raw exceptions and backend data are excluded. */
|
|
19
|
+
export declare class BackendReadRefusal extends Error {
|
|
20
|
+
/** Classify the failed probe without parsing an exception message. */
|
|
21
|
+
readonly status: "unavailable" | "invariant_failed";
|
|
22
|
+
/** Construct a typed provider failure. */
|
|
23
|
+
constructor(status: "unavailable" | "invariant_failed");
|
|
24
|
+
}
|
|
25
|
+
/** Invalid configuration is refused before any backend reads. */
|
|
26
|
+
export declare class BackendConfigurationRefusal extends Error {
|
|
27
|
+
/** Stable input failure code. */
|
|
28
|
+
readonly code: "invalid_adapter_ids" | "invalid_backend_config" | "invalid_backend_endpoint";
|
|
29
|
+
/** Safe recovery instructions, excluding the supplied value. */
|
|
30
|
+
readonly remedy: string;
|
|
31
|
+
/** Build an actionable configuration failure. */
|
|
32
|
+
constructor(code: BackendConfigurationRefusal["code"], remedy: string);
|
|
33
|
+
}
|
|
34
|
+
/** Compact, data-free evidence for one adapter and operation. */
|
|
35
|
+
export interface BackendCapabilityRow {
|
|
36
|
+
/** Adapter label, never its connection string. */
|
|
37
|
+
adapter: string;
|
|
38
|
+
/** Storage category. */
|
|
39
|
+
kind: BackendReadAdapter["kind"];
|
|
40
|
+
/** Read contract that was audited. */
|
|
41
|
+
operation: BackendOperation;
|
|
42
|
+
/** Independent outcome. */
|
|
43
|
+
status: BackendCapabilityStatus;
|
|
44
|
+
/** Stable machine-readable refusal code, or verified. */
|
|
45
|
+
code: "verified" | `backend_${Exclude<BackendCapabilityStatus, "supported">}`;
|
|
46
|
+
/** Count of verified rows or schema types. */
|
|
47
|
+
checked: number;
|
|
48
|
+
/** Action to resolve a refusal. */
|
|
49
|
+
remedy: string;
|
|
50
|
+
}
|
|
51
|
+
/** Agent-sized report containing three rows per configured adapter. */
|
|
52
|
+
export interface BackendCapabilityMatrix {
|
|
53
|
+
/** Version of this report and normalized read contract. */
|
|
54
|
+
version: 1;
|
|
55
|
+
/** True only when every declared operation was verified. Unsupported declarations remain visible. */
|
|
56
|
+
ok: boolean;
|
|
57
|
+
/** Exactly one row per adapter/operation pair. */
|
|
58
|
+
rows: BackendCapabilityRow[];
|
|
59
|
+
/** Totals by outcome. */
|
|
60
|
+
counts: Record<BackendCapabilityStatus, number>;
|
|
61
|
+
}
|
|
62
|
+
/** Audit every configured adapter using only its declared read ports, without returning tracker data. */
|
|
63
|
+
export declare function auditBackendCapabilities(adapters: readonly BackendReadAdapter[]): Promise<BackendCapabilityMatrix>;
|
|
64
|
+
/** Declarative CLI adapter configuration. Remote endpoints implement the normalized read bridge, not native SQL or MCP. */
|
|
65
|
+
export interface BackendAdapterConfig {
|
|
66
|
+
/** Public adapter label. */
|
|
67
|
+
id: string;
|
|
68
|
+
/** Storage category. */
|
|
69
|
+
kind: BackendReadAdapter["kind"];
|
|
70
|
+
/** Directory tracker root, relative to the configuration file. */
|
|
71
|
+
root?: string;
|
|
72
|
+
/** HTTP read bridge URL; credentials must be supplied through its deployment, never URL userinfo. */
|
|
73
|
+
endpoint?: string;
|
|
74
|
+
/** Declared read support. */
|
|
75
|
+
operations: readonly BackendOperation[];
|
|
76
|
+
}
|
|
77
|
+
/** Parse configuration without executing code or accepting ambiguous connection options. */
|
|
78
|
+
export declare function parseBackendConfig(value: unknown): BackendAdapterConfig[];
|
|
79
|
+
/** Audit configured adapters, removing disposable SDK cache snapshots even when reads fail. */
|
|
80
|
+
export declare function auditConfiguredBackends(config: readonly BackendAdapterConfig[], base: string): Promise<BackendCapabilityMatrix>;
|
|
81
|
+
/** Read a JSON adapter configuration relative to its own directory. */
|
|
82
|
+
export declare function auditBackendConfigFile(path: string): Promise<BackendCapabilityMatrix>;
|
|
83
|
+
//# sourceMappingURL=backend-capabilities.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"backend-capabilities.d.ts","sourceRoot":"","sources":["../backend-capabilities.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,255 @@
|
|
|
1
|
+
/** Read-only backend contract assurance; never runs Git or tracker mutations. */
|
|
2
|
+
import { chmod, cp, lstat, mkdtemp, readFile, readdir, rm } from "node:fs/promises";
|
|
3
|
+
import { tmpdir } from "node:os";
|
|
4
|
+
import { dirname, join, resolve } from "node:path";
|
|
5
|
+
import { listAllItemMetadata, locateItem, readLocatedItem, readSettings, resolveItemTypeRegistry } from "@unbrained/pm-cli/sdk";
|
|
6
|
+
/** Fixed audited read surface. Mutations are deliberately outside this contract. */
|
|
7
|
+
export const BACKEND_OPERATIONS = ["list", "get", "schema"];
|
|
8
|
+
/** Typed refusal with a safe remedy; raw exceptions and backend data are excluded. */
|
|
9
|
+
export class BackendReadRefusal extends Error {
|
|
10
|
+
/** Classify the failed probe without parsing an exception message. */
|
|
11
|
+
status;
|
|
12
|
+
/** Construct a typed provider failure. */
|
|
13
|
+
constructor(status) {
|
|
14
|
+
super(status);
|
|
15
|
+
this.name = "BackendReadRefusal";
|
|
16
|
+
this.status = status;
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
/** Invalid configuration is refused before any backend reads. */
|
|
20
|
+
export class BackendConfigurationRefusal extends Error {
|
|
21
|
+
/** Stable input failure code. */
|
|
22
|
+
code;
|
|
23
|
+
/** Safe recovery instructions, excluding the supplied value. */
|
|
24
|
+
remedy;
|
|
25
|
+
/** Build an actionable configuration failure. */
|
|
26
|
+
constructor(code, remedy) {
|
|
27
|
+
super(`${code}: ${remedy}`);
|
|
28
|
+
this.name = "BackendConfigurationRefusal";
|
|
29
|
+
this.code = code;
|
|
30
|
+
this.remedy = remedy;
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
/** Narrow a transport value to a non-array record. */
|
|
34
|
+
function record(value) {
|
|
35
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
36
|
+
}
|
|
37
|
+
/** Validate complete list evidence before selecting a deterministic get probe. */
|
|
38
|
+
function listIds(value) {
|
|
39
|
+
if (!record(value) || value.complete !== true || !Array.isArray(value.items) || value.count !== value.items.length) {
|
|
40
|
+
throw new BackendReadRefusal("invariant_failed");
|
|
41
|
+
}
|
|
42
|
+
const ids = value.items.map((item) => {
|
|
43
|
+
if (!record(item) || typeof item.id !== "string" || !item.id.trim())
|
|
44
|
+
throw new BackendReadRefusal("invariant_failed");
|
|
45
|
+
return item.id;
|
|
46
|
+
});
|
|
47
|
+
if (new Set(ids).size !== ids.length)
|
|
48
|
+
throw new BackendReadRefusal("invariant_failed");
|
|
49
|
+
return ids.sort();
|
|
50
|
+
}
|
|
51
|
+
/** Verify one schema read without returning schema contents. */
|
|
52
|
+
function schemaCount(value) {
|
|
53
|
+
if (!record(value) || !Array.isArray(value.types) || value.types.length === 0
|
|
54
|
+
|| !value.types.every((type) => typeof type === "string" && type.trim().length > 0)
|
|
55
|
+
|| new Set(value.types).size !== value.types.length)
|
|
56
|
+
throw new BackendReadRefusal("invariant_failed");
|
|
57
|
+
return value.types.length;
|
|
58
|
+
}
|
|
59
|
+
/** Audit every configured adapter using only its declared read ports, without returning tracker data. */
|
|
60
|
+
export async function auditBackendCapabilities(adapters) {
|
|
61
|
+
if (adapters.length === 0 || adapters.length > 32 || new Set(adapters.map((adapter) => adapter.id)).size !== adapters.length
|
|
62
|
+
|| adapters.some((adapter) => !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(adapter.id))) {
|
|
63
|
+
throw new BackendConfigurationRefusal("invalid_adapter_ids", "use unique public labels of 1-64 letters, digits, underscores or hyphens");
|
|
64
|
+
}
|
|
65
|
+
const rows = [];
|
|
66
|
+
const counts = { supported: 0, unsupported: 0, unavailable: 0, invariant_failed: 0, unverified: 0 };
|
|
67
|
+
for (const adapter of adapters) {
|
|
68
|
+
let ids = [];
|
|
69
|
+
for (const operation of BACKEND_OPERATIONS) {
|
|
70
|
+
let status = "supported";
|
|
71
|
+
let checked = 0;
|
|
72
|
+
if (!adapter.operations.includes(operation))
|
|
73
|
+
status = "unsupported";
|
|
74
|
+
else if (operation === "get" && ids.length === 0)
|
|
75
|
+
status = "unverified";
|
|
76
|
+
else {
|
|
77
|
+
try {
|
|
78
|
+
const value = await adapter.read(operation, operation === "get" ? ids[0] : undefined);
|
|
79
|
+
if (operation === "list") {
|
|
80
|
+
ids = listIds(value);
|
|
81
|
+
checked = ids.length;
|
|
82
|
+
}
|
|
83
|
+
else if (operation === "schema")
|
|
84
|
+
checked = schemaCount(value);
|
|
85
|
+
else {
|
|
86
|
+
if (!record(value) || value.id !== ids[0])
|
|
87
|
+
throw new BackendReadRefusal("invariant_failed");
|
|
88
|
+
checked = 1;
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
catch (error) {
|
|
92
|
+
status = error instanceof BackendReadRefusal ? error.status : "unavailable";
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
const remedies = {
|
|
96
|
+
supported: "",
|
|
97
|
+
unsupported: "Use an adapter declaring this read operation.",
|
|
98
|
+
unavailable: "Check connection, read credentials and bridge compatibility; retry.",
|
|
99
|
+
invariant_failed: "Repair the read contract or tracker integrity, then retry on a stable snapshot.",
|
|
100
|
+
unverified: "Provide a nonempty complete list to verify get; no synthetic item is created.",
|
|
101
|
+
};
|
|
102
|
+
counts[status] += 1;
|
|
103
|
+
rows.push({ adapter: adapter.id, kind: adapter.kind, operation, status, code: status === "supported" ? "verified" : `backend_${status}`, checked, remedy: remedies[status] });
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
return { version: 1, ok: counts.unavailable + counts.invariant_failed + counts.unverified === 0, rows, counts };
|
|
107
|
+
}
|
|
108
|
+
/** Parse configuration without executing code or accepting ambiguous connection options. */
|
|
109
|
+
export function parseBackendConfig(value) {
|
|
110
|
+
if (!Array.isArray(value) || value.length === 0 || value.length > 32)
|
|
111
|
+
throw new BackendConfigurationRefusal("invalid_backend_config", "configure 1-32 adapters");
|
|
112
|
+
return value.map((entry) => {
|
|
113
|
+
if (!record(entry) || typeof entry.id !== "string"
|
|
114
|
+
|| !["directory", "database", "mcp"].includes(String(entry.kind)) || !Array.isArray(entry.operations)
|
|
115
|
+
|| !entry.operations.every((op) => BACKEND_OPERATIONS.includes(op))
|
|
116
|
+
|| new Set(entry.operations).size !== entry.operations.length
|
|
117
|
+
|| (entry.kind === "directory" ? typeof entry.root !== "string" || !entry.root : typeof entry.endpoint !== "string")) {
|
|
118
|
+
throw new BackendConfigurationRefusal("invalid_backend_config", "supply id, kind, unique operations and root or endpoint");
|
|
119
|
+
}
|
|
120
|
+
if (entry.kind !== "directory") {
|
|
121
|
+
let endpoint;
|
|
122
|
+
try {
|
|
123
|
+
endpoint = new URL(entry.endpoint);
|
|
124
|
+
}
|
|
125
|
+
catch {
|
|
126
|
+
throw new BackendConfigurationRefusal("invalid_backend_endpoint", "use an HTTP read bridge URL");
|
|
127
|
+
}
|
|
128
|
+
if (!["http:", "https:"].includes(endpoint.protocol) || endpoint.username || endpoint.password || endpoint.hash) {
|
|
129
|
+
throw new BackendConfigurationRefusal("invalid_backend_endpoint", "use HTTP(S) without URL credentials or fragments");
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
return entry;
|
|
133
|
+
});
|
|
134
|
+
}
|
|
135
|
+
/** Copy only authoritative settings and registered item folders; reject links escaping the snapshot. */
|
|
136
|
+
async function directorySnapshot(root, target) {
|
|
137
|
+
const settingsPath = join(root, "settings.json");
|
|
138
|
+
if ((await lstat(root)).isSymbolicLink() || (await lstat(settingsPath)).isSymbolicLink())
|
|
139
|
+
throw new BackendReadRefusal("invariant_failed");
|
|
140
|
+
await cp(settingsPath, join(target, "settings.json"));
|
|
141
|
+
const settings = await readSettings(target);
|
|
142
|
+
const registry = resolveItemTypeRegistry(settings);
|
|
143
|
+
for (const folder of new Set(Object.values(registry.type_to_folder))) {
|
|
144
|
+
try {
|
|
145
|
+
await lstat(join(root, folder));
|
|
146
|
+
}
|
|
147
|
+
catch (error) {
|
|
148
|
+
if (error.code === "ENOENT")
|
|
149
|
+
continue;
|
|
150
|
+
throw error;
|
|
151
|
+
}
|
|
152
|
+
await cp(join(root, folder), join(target, folder), { recursive: true, filter: async (source) => {
|
|
153
|
+
if ((await lstat(source)).isSymbolicLink())
|
|
154
|
+
throw new BackendReadRefusal("invariant_failed");
|
|
155
|
+
return true;
|
|
156
|
+
} });
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
/** Bind isolated directory SDK reads; the original tracker is never passed to cache-writing SDK helpers. */
|
|
160
|
+
async function directoryRead(root, operation, id) {
|
|
161
|
+
const settings = await readSettings(root);
|
|
162
|
+
const registry = resolveItemTypeRegistry(settings);
|
|
163
|
+
if (operation === "schema")
|
|
164
|
+
return { types: registry.types };
|
|
165
|
+
const warnings = [];
|
|
166
|
+
if (operation === "list") {
|
|
167
|
+
const items = await listAllItemMetadata(root, settings.item_format, registry.type_to_folder, warnings, settings.schema);
|
|
168
|
+
if (warnings.length)
|
|
169
|
+
throw new BackendReadRefusal("invariant_failed");
|
|
170
|
+
return { items, count: items.length, complete: true };
|
|
171
|
+
}
|
|
172
|
+
const item = await locateItem(root, id, settings.id_prefix, settings.item_format, registry.type_to_folder);
|
|
173
|
+
if (!item)
|
|
174
|
+
throw new BackendReadRefusal("invariant_failed");
|
|
175
|
+
const result = await readLocatedItem(item, { schema: settings.schema });
|
|
176
|
+
return result.document.metadata;
|
|
177
|
+
}
|
|
178
|
+
/** Relax owned snapshot directories before reading their children, even after a partial copy. */
|
|
179
|
+
async function relaxSnapshotPermissions(root) {
|
|
180
|
+
try {
|
|
181
|
+
await chmod(root, 0o700);
|
|
182
|
+
for (const entry of await readdir(root, { withFileTypes: true })) {
|
|
183
|
+
if (entry.isDirectory())
|
|
184
|
+
await relaxSnapshotPermissions(join(root, entry.name));
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
catch {
|
|
188
|
+
// Permission repair is best effort; removal must still be attempted.
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
/** Audit configured adapters, removing disposable SDK cache snapshots even when reads fail. */
|
|
192
|
+
export async function auditConfiguredBackends(config, base) {
|
|
193
|
+
parseBackendConfig(config);
|
|
194
|
+
const scratch = await mkdtemp(join(tmpdir(), "pm-backend-"));
|
|
195
|
+
try {
|
|
196
|
+
const adapters = [];
|
|
197
|
+
for (const [index, entry] of config.entries()) {
|
|
198
|
+
const snapshot = join(scratch, String(index));
|
|
199
|
+
let failure;
|
|
200
|
+
if (entry.kind === "directory") {
|
|
201
|
+
try {
|
|
202
|
+
await directorySnapshot(resolve(base, entry.root), snapshot);
|
|
203
|
+
}
|
|
204
|
+
catch (error) {
|
|
205
|
+
failure = error;
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
adapters.push({ ...entry, read: async (operation, id) => {
|
|
209
|
+
if (failure)
|
|
210
|
+
throw failure;
|
|
211
|
+
if (entry.kind === "directory")
|
|
212
|
+
return directoryRead(snapshot, operation, id);
|
|
213
|
+
const url = new URL(entry.endpoint);
|
|
214
|
+
url.searchParams.set("operation", operation);
|
|
215
|
+
if (id !== undefined)
|
|
216
|
+
url.searchParams.set("id", id);
|
|
217
|
+
const response = await fetch(url, { method: "GET", redirect: "error", signal: AbortSignal.timeout(5000), headers: { accept: "application/json" } });
|
|
218
|
+
if (!response.ok)
|
|
219
|
+
throw new BackendReadRefusal("unavailable");
|
|
220
|
+
try {
|
|
221
|
+
return await response.json();
|
|
222
|
+
}
|
|
223
|
+
catch {
|
|
224
|
+
throw new BackendReadRefusal("invariant_failed");
|
|
225
|
+
}
|
|
226
|
+
} });
|
|
227
|
+
}
|
|
228
|
+
return await auditBackendCapabilities(adapters);
|
|
229
|
+
}
|
|
230
|
+
finally {
|
|
231
|
+
try {
|
|
232
|
+
await relaxSnapshotPermissions(scratch);
|
|
233
|
+
}
|
|
234
|
+
finally {
|
|
235
|
+
try {
|
|
236
|
+
await rm(scratch, { recursive: true, force: true });
|
|
237
|
+
}
|
|
238
|
+
catch {
|
|
239
|
+
// Cleanup failure must not replace the audit evidence or original error.
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
/** Read a JSON adapter configuration relative to its own directory. */
|
|
245
|
+
export async function auditBackendConfigFile(path) {
|
|
246
|
+
let value;
|
|
247
|
+
try {
|
|
248
|
+
value = JSON.parse(await readFile(path, "utf8"));
|
|
249
|
+
}
|
|
250
|
+
catch {
|
|
251
|
+
throw new BackendConfigurationRefusal("invalid_backend_config", "provide a readable JSON adapter array");
|
|
252
|
+
}
|
|
253
|
+
return auditConfiguredBackends(parseBackendConfig(value), dirname(resolve(path)));
|
|
254
|
+
}
|
|
255
|
+
//# sourceMappingURL=backend-capabilities.js.map
|