@intellectual-frontiers/ergonex 0.2.5 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/README.md +2 -0
  2. package/dist/desired.d.ts +27 -0
  3. package/dist/diff.d.ts +12 -0
  4. package/dist/doctor.d.ts +79 -0
  5. package/dist/findings.d.ts +85 -0
  6. package/dist/layout.d.ts +83 -0
  7. package/dist/manifest.d.ts +84 -0
  8. package/dist/mod.d.ts +29 -0
  9. package/dist/mod.js +4219 -0
  10. package/dist/modules/external.d.ts +31 -0
  11. package/dist/modules/mod.d.ts +10 -0
  12. package/dist/modules/name.d.ts +32 -0
  13. package/dist/modules/registry.d.ts +51 -0
  14. package/dist/modules/types.d.ts +178 -0
  15. package/dist/places.d.ts +35 -0
  16. package/dist/plan.d.ts +176 -0
  17. package/dist/platform/k-args.d.ts +28 -0
  18. package/dist/policy.d.ts +39 -0
  19. package/dist/portable.d.ts +111 -0
  20. package/dist/render.d.ts +95 -0
  21. package/dist/setup/evidence.d.ts +58 -0
  22. package/dist/shell/block.d.ts +45 -0
  23. package/dist/shell/mod.d.ts +8 -0
  24. package/dist/shell/snippet.d.ts +43 -0
  25. package/dist/state-record.d.ts +59 -0
  26. package/dist/state.d.ts +64 -0
  27. package/dist/templates/data.d.ts +25 -0
  28. package/dist/templates/hooks.d.ts +13 -0
  29. package/dist/templates/mod.d.ts +16 -0
  30. package/dist/tools/catalog.d.ts +70 -0
  31. package/dist/types.d.ts +51 -0
  32. package/dist/vendor/ts/githost/capabilities.d.ts +18 -0
  33. package/dist/vendor/ts/githost/git.d.ts +16 -0
  34. package/dist/vendor/ts/githost/github.d.ts +15 -0
  35. package/dist/vendor/ts/githost/gitlab.d.ts +15 -0
  36. package/dist/vendor/ts/githost/mod.d.ts +29 -0
  37. package/dist/vendor/ts/githost/remote.d.ts +59 -0
  38. package/dist/vendor/ts/githost/types.d.ts +101 -0
  39. package/dist/vendor/ts/kernel/archive.d.ts +147 -0
  40. package/dist/vendor/ts/kernel/args.d.ts +240 -0
  41. package/dist/vendor/ts/kernel/assess.d.ts +247 -0
  42. package/dist/vendor/ts/kernel/attest.d.ts +164 -0
  43. package/dist/vendor/ts/kernel/base64.d.ts +24 -0
  44. package/dist/vendor/ts/kernel/cbor.d.ts +39 -0
  45. package/dist/vendor/ts/kernel/cms.d.ts +106 -0
  46. package/dist/vendor/ts/kernel/commands.d.ts +103 -0
  47. package/dist/vendor/ts/kernel/cose.d.ts +34 -0
  48. package/dist/vendor/ts/kernel/crypt.d.ts +30 -0
  49. package/dist/vendor/ts/kernel/csv.d.ts +38 -0
  50. package/dist/vendor/ts/kernel/der.d.ts +67 -0
  51. package/dist/vendor/ts/kernel/documentation.d.ts +118 -0
  52. package/dist/vendor/ts/kernel/dsse.d.ts +137 -0
  53. package/dist/vendor/ts/kernel/evidence.d.ts +212 -0
  54. package/dist/vendor/ts/kernel/glob.d.ts +64 -0
  55. package/dist/vendor/ts/kernel/grc.d.ts +356 -0
  56. package/dist/vendor/ts/kernel/http.d.ts +46 -0
  57. package/dist/vendor/ts/kernel/json5.d.ts +46 -0
  58. package/dist/vendor/ts/kernel/layers.d.ts +35 -0
  59. package/dist/vendor/ts/kernel/md5.d.ts +19 -0
  60. package/dist/vendor/ts/kernel/media-types.d.ts +28 -0
  61. package/dist/vendor/ts/kernel/mod.d.ts +95 -0
  62. package/dist/vendor/ts/kernel/ocsf-types.auto.d.ts +4374 -0
  63. package/dist/vendor/ts/kernel/ocsf.d.ts +160 -0
  64. package/dist/vendor/ts/kernel/oscal.d.ts +356 -0
  65. package/dist/vendor/ts/kernel/otel.d.ts +365 -0
  66. package/dist/vendor/ts/kernel/otlp.d.ts +83 -0
  67. package/dist/vendor/ts/kernel/palette.d.ts +44 -0
  68. package/dist/vendor/ts/kernel/png.d.ts +124 -0
  69. package/dist/vendor/ts/kernel/rdf-schema.d.ts +190 -0
  70. package/dist/vendor/ts/kernel/rdf-term.d.ts +162 -0
  71. package/dist/vendor/ts/kernel/rdf-vocabularies.d.ts +148 -0
  72. package/dist/vendor/ts/kernel/rdf-write.d.ts +25 -0
  73. package/dist/vendor/ts/kernel/rdf.d.ts +35 -0
  74. package/dist/vendor/ts/kernel/render.d.ts +111 -0
  75. package/dist/vendor/ts/kernel/schedule.d.ts +207 -0
  76. package/dist/vendor/ts/kernel/semver.d.ts +94 -0
  77. package/dist/vendor/ts/kernel/sha256.d.ts +29 -0
  78. package/dist/vendor/ts/kernel/signals.d.ts +371 -0
  79. package/dist/vendor/ts/kernel/sigv4.d.ts +67 -0
  80. package/dist/vendor/ts/kernel/test-record.d.ts +222 -0
  81. package/dist/vendor/ts/kernel/test-report.d.ts +294 -0
  82. package/dist/vendor/ts/kernel/toml.d.ts +51 -0
  83. package/dist/vendor/ts/kernel/trace.d.ts +169 -0
  84. package/dist/vendor/ts/kernel/ts-literal.d.ts +62 -0
  85. package/dist/vendor/ts/kernel/uuid.d.ts +53 -0
  86. package/dist/vendor/ts/kernel/vt.d.ts +78 -0
  87. package/dist/vendor/ts/kernel/webauthn.d.ts +212 -0
  88. package/dist/vendor/ts/kernel/width.d.ts +63 -0
  89. package/dist/vendor/ts/kernel/xml.d.ts +73 -0
  90. package/dist/vendor/ts/kernel/yaml.d.ts +44 -0
  91. package/dist/vendor/ts/runtime/http-client.d.ts +149 -0
  92. package/ergonex.mjs +140 -140
  93. package/package.json +17 -5
@@ -0,0 +1,51 @@
1
+ /**
2
+ * The branded types of Intellectual Frontiers Workspaces (commons 0002-workspace-model FR-006 to FR-012): a Git host's name, a path segment that is valid on Linux, macOS and Windows alike, a
3
+ * path of the workspace, a branch, a commit and a pinned version are each a type of their own, made only by the function that refuses what it should, so that an unchecked string never
4
+ * reaches the layout or the plan.
5
+ *
6
+ * @remarks
7
+ * `PortableSegment` and `RepoPath` are made in `portable.ts`; the others are made here. A refusal is a `Result` whose error says what is wrong and names the text, never a throw.
8
+ *
9
+ * @module
10
+ */
11
+ import { type Result } from "@intellectual-frontiers/core";
12
+ import type { Brand } from "@intellectual-frontiers/core";
13
+ /** One name in a path, valid on every operating system (made only by `segment` in `portable.ts`). */
14
+ export type PortableSegment = Brand<string, "PortableSegment">;
15
+ /** A path of the workspace below its root: portable segments with `/` between them, never absolute and never holding `..` (made only by `repoPath` in `portable.ts`). */
16
+ export type RepoPath = Brand<string, "RepoPath">;
17
+ /** A Git host's name in lower case, as the first folder of a repository's path (`github.com`). */
18
+ export type GitHost = Brand<string, "GitHost">;
19
+ /** A branch's name, by the rules of `git check-ref-format --branch`. */
20
+ export type BranchName = Brand<string, "BranchName">;
21
+ /** A commit's object id: 40 (SHA-1) or 64 (SHA-256) lower-case hexadecimal digits. */
22
+ export type Sha = Brand<string, "Sha">;
23
+ /** A pinned version of a tool: `major.minor.patch` with an optional pre-release and build, never `latest` and never a range. */
24
+ export type Version = Brand<string, "Version">;
25
+ /** A text refused as a type of this module, and why. */
26
+ export type BrandError = {
27
+ readonly kind: "git-host";
28
+ readonly text: string;
29
+ readonly reason: string;
30
+ } | {
31
+ readonly kind: "branch-name";
32
+ readonly text: string;
33
+ readonly reason: string;
34
+ } | {
35
+ readonly kind: "sha";
36
+ readonly text: string;
37
+ } | {
38
+ readonly kind: "version";
39
+ readonly text: string;
40
+ readonly reason: string;
41
+ };
42
+ /** A refusal as one sentence. */
43
+ export declare function describeBrandError(e: BrandError): string;
44
+ /** A Git host's name: letters, digits, `-`, `_` and `.` between labels, lower-cased; no port, no scheme, no credential. */
45
+ export declare function gitHost(text: string): Result<GitHost, BrandError>;
46
+ /** A branch's name, by the rules of Git's ref names (`git check-ref-format`): no control character, space, `~ ^ : ? * [ \`, `..` or `@{`, no component that starts with `.` or ends in `.lock`, and no start with `-`. */
47
+ export declare function branchName(text: string): Result<BranchName, BrandError>;
48
+ /** A commit id. */
49
+ export declare function sha(text: string): Result<Sha, BrandError>;
50
+ /** A pinned version: a semantic version with no `v` and nothing around it, so `latest`, `1.x`, `^1.2.0`, `>=1` and `v1.2.3` are refused (0002-workspace-model FR-037). */
51
+ export declare function version(text: string): Result<Version, BrandError>;
@@ -0,0 +1,18 @@
1
+ /**
2
+ * What each kind of Git host offers (commons 0020-ifccm FR-040, FR-017): the table of `ifccm:GitManagerKind` and its `ifccm:supports`, as the pure types the adapters and the
3
+ * workspace read, and the typed answer for a capability a kind lacks. A test holds this table equal to the ontology's.
4
+ *
5
+ * @module
6
+ */
7
+ import { type Result } from "@intellectual-frontiers/core";
8
+ import type { Capability, HostFailure, HostKind } from "./types.js";
9
+ /** The four capabilities every kind offers (`ifccm:CloneUrl`, `ifccm:Credentials`, `ifccm:DefaultBranch`, `ifccm:SignedCommits`). */
10
+ export declare const COMMON_CAPABILITIES: readonly Capability[];
11
+ /** The capabilities of each kind: GitHub the common four and the three a host adds, GitLab those and groups to any depth, plain Git the common four alone. */
12
+ export declare const CAPABILITIES: Readonly<Record<HostKind, ReadonlySet<Capability>>>;
13
+ /** Whether a kind of host offers a capability. */
14
+ export declare function supports(kind: HostKind, capability: Capability): boolean;
15
+ /** The answer for a capability that a kind of host does not offer: typed, naming the host and the capability, never a guess (0020-ifccm FR-041). */
16
+ export declare function unsupported(host: HostKind, capability: Capability): Result<never, HostFailure>;
17
+ /** The most path segments (owner or groups, then repository) a kind of host takes: 2 where it has no nested groups, unlimited where it has. */
18
+ export declare function maxDepth(kind: HostKind): number;
@@ -0,0 +1,16 @@
1
+ import type { GitHostClient, RepoRef } from "./types.js";
2
+ /** How a plain Git client is made. */
3
+ export type PlainGitOptions = {
4
+ /** The program (`git` on the path by default). */
5
+ readonly program?: string;
6
+ /** The URL or path a repository is asked from; its HTTPS clone URL by default. Never one with a credential in it. */
7
+ readonly remoteOf?: (ref: RepoRef) => string;
8
+ /** A clone of the repository on this computer, where the signature of a commit can be read; none by default (a signature is then `not-found`). */
9
+ readonly localOf?: (ref: RepoRef) => string | undefined;
10
+ /** Variables added to `git`'s environment (a test points `GIT_CONFIG_GLOBAL` at its own file; nothing here may be a credential). */
11
+ readonly env?: Readonly<Record<string, string>>;
12
+ };
13
+ /** The branch a `git ls-remote --symref <url> HEAD` says HEAD points to: empty where it says none (an empty repository). */
14
+ export declare function defaultBranchOf(lsRemote: string): string;
15
+ /** A plain Git client: the common four capabilities, and `unsupported` for protected branches, issues and change requests. */
16
+ export declare function plainGitClient(options?: PlainGitOptions): GitHostClient;
@@ -0,0 +1,15 @@
1
+ import type { Transport } from "../runtime/http-client.js";
2
+ import type { GitHostClient } from "./types.js";
3
+ /** How a GitHub client is made. */
4
+ export type GithubOptions = {
5
+ /** How requests are sent: the live transport, or a recorded one. */
6
+ readonly transport: Transport;
7
+ /** A token, from the environment by the caller; never stored in a file and never in a result. Absent: only what is public. */
8
+ readonly token?: string | undefined;
9
+ /** The one host this client serves (`github.com` by default); a reference to another host is `not-found`, so the token is never sent elsewhere. */
10
+ readonly host?: string;
11
+ /** The API's base URL (`https://api.github.com` for `github.com`, `https://<host>/api/v3` for another host by default). */
12
+ readonly apiBase?: string;
13
+ };
14
+ /** A GitHub client over a transport: the common four capabilities and protected branches, issues and pull requests, with no nested groups. */
15
+ export declare function githubClient(options: GithubOptions): GitHostClient;
@@ -0,0 +1,15 @@
1
+ import type { Transport } from "../runtime/http-client.js";
2
+ import type { GitHostClient } from "./types.js";
3
+ /** How a GitLab client is made. */
4
+ export type GitlabOptions = {
5
+ /** How requests are sent: the live transport, or a recorded one. */
6
+ readonly transport: Transport;
7
+ /** The host's address without the API path (`https://gitlab.com` by default); its host name is the one host this client serves. */
8
+ readonly baseUrl?: string;
9
+ /** A token, from the environment by the caller; never stored in a file and never in a result. Absent: only what is public. */
10
+ readonly token?: string | undefined;
11
+ /** What the token is: a personal or project access token (`PRIVATE-TOKEN`, the default), or a CI job's token (`JOB-TOKEN`). */
12
+ readonly tokenKind?: "access" | "job";
13
+ };
14
+ /** A GitLab client over a transport: the common four capabilities, protected branches, issues and merge requests, and groups to any depth. */
15
+ export declare function gitlabClient(options: GitlabOptions): GitHostClient;
@@ -0,0 +1,29 @@
1
+ import { type Transport } from "../runtime/http-client.js";
2
+ import { type PlainGitOptions } from "./git.js";
3
+ import type { GitHostClient, RepoRef } from "./types.js";
4
+ export { CAPABILITIES, COMMON_CAPABILITIES, maxDepth, supports, unsupported } from "./capabilities.js";
5
+ export { githubClient, type GithubOptions } from "./github.js";
6
+ export { defaultBranchOf, plainGitClient, type PlainGitOptions } from "./git.js";
7
+ export { gitlabClient, type GitlabOptions } from "./gitlab.js";
8
+ export { cloneUrlOf, describeRef, describeRemoteError, hostKindOf, type HostKinds, parseRemote, readRemote, type ReadRemote, type RemoteError, sameRepository, } from "./remote.js";
9
+ export { type BranchProtection, type Capability, type ChangeRequestInfo, describeFailure, type GitHostClient, type HostFailure, type HostKind, type HostResult, type IssueInfo, type RepoInfo, type RepoRef, type Visibility, } from "./types.js";
10
+ /** What `clientFor` reads and uses. */
11
+ export type ClientForOptions = {
12
+ /** The caller's environment: where the token is read from, and nowhere else. */
13
+ readonly env: Readonly<Record<string, string | undefined>>;
14
+ /** How requests are sent; the live transport (with backoff, and a credential allowed only where a token is given) by default. */
15
+ readonly transport?: Transport;
16
+ /** For a plain Git remote: where it is asked from and where a clone is. */
17
+ readonly plain?: PlainGitOptions;
18
+ /**
19
+ * The hosts, besides `github.com` and `gitlab.com`, that may be sent a token: those the manifest names (a self-managed GitLab, GitHub Enterprise Server). A host not here is asked with no
20
+ * credential, so that an environment's token is never sent to a host nobody named.
21
+ */
22
+ readonly trustedHosts?: readonly string[];
23
+ /** The base URL of a self-managed GitLab, where the reference's host is not `gitlab.com` and is not served over `https://<host>`. */
24
+ readonly gitlabBaseUrl?: string;
25
+ /** The API's base URL of a GitHub Enterprise Server host, where it is not `https://<host>/api/v3`. */
26
+ readonly githubApiBase?: string;
27
+ };
28
+ /** The client for a reference's kind of host, with the token the environment holds for it, if any and if the host may receive one. */
29
+ export declare function clientFor(ref: RepoRef, options: ClientForOptions): GitHostClient;
@@ -0,0 +1,59 @@
1
+ /**
2
+ * A Git remote URL read as a repository on a host (commons 0020-ifccm FR-039, FR-019): the https, `git://`, `ssh://` and scp-like (`git@host:owner/repo`) forms give the same
3
+ * `RepoRef`, whichever way the remote is written, so that a clone made over SSH is the repository the manifest names over HTTPS.
4
+ *
5
+ * @remarks
6
+ * A credential in the URL (`https://user:token@host/...`) is dropped: no result, no error and no message holds it. The host name is lower-cased and its port is dropped (an SSH port and
7
+ * an HTTPS port say how to reach a host, not which repository it is); the path is kept as the host writes it, without `.git` and without a trailing slash. The kind of host is GitHub for
8
+ * `github.com`, GitLab for `gitlab.com` and for a host a map names, and plain Git for every other: a self-managed GitLab is named, never guessed from a URL (FR-019).
9
+ *
10
+ * @limits It reads no file and asks no host. A local path or a `file:` URL is not a remote of a host and is an error.
11
+ *
12
+ * @module
13
+ */
14
+ import { type Result } from "@intellectual-frontiers/core";
15
+ import type { HostKind, RepoRef } from "./types.js";
16
+ /** Why a text is not a remote URL of a repository on a host. Never holds the URL, which may hold a credential. */
17
+ export type RemoteError = {
18
+ readonly kind: "empty";
19
+ } | {
20
+ readonly kind: "local-path";
21
+ } | {
22
+ readonly kind: "unsupported-scheme";
23
+ readonly scheme: string;
24
+ } | {
25
+ readonly kind: "no-host";
26
+ } | {
27
+ readonly kind: "no-path";
28
+ } | {
29
+ readonly kind: "bad-segment";
30
+ readonly reason: string;
31
+ };
32
+ /** A remote error as one sentence. */
33
+ export declare function describeRemoteError(e: RemoteError): string;
34
+ /** The hosts that are not plain Git, by name: a map from a lower-case host name to its kind, as the manifest names them (a self-managed GitLab, or GitHub Enterprise Server). */
35
+ export type HostKinds = Readonly<Record<string, HostKind>>;
36
+ /** The kind of a host: GitHub for `github.com`, GitLab for `gitlab.com`, what the map says for a host it names, and plain Git for every other (0020-ifccm FR-043). */
37
+ export declare function hostKindOf(host: string, hostKinds?: HostKinds): HostKind;
38
+ /**
39
+ * A remote URL as the repository it names. The forms: `https://host/path(.git)`, `http://`, `git://`, `ssh://[user@]host[:port]/path(.git)` and `[user@]host:path(.git)`. A credential in
40
+ * the URL is dropped; `hostKinds` names the hosts that are not plain Git.
41
+ */
42
+ export declare function parseRemote(url: string, hostKinds?: HostKinds): Result<RepoRef, RemoteError>;
43
+ /** A remote as a person writes it: the repository, and the branch where the text is the address of a branch's page. */
44
+ export type ReadRemote = {
45
+ readonly ref: RepoRef;
46
+ readonly branch?: string;
47
+ };
48
+ /**
49
+ * A remote as a person writes it, where the domain says the rest: `github.com/owner/repo` and `gitlab.example.com/group/sub/repo` need no `https://`, `owner/repo` is a repository of GitHub,
50
+ * `github:owner/repo` and `gitlab:group/sub/repo` name the host's kind, and the address of a branch's page (`.../tree/main`) is the repository and that branch. Every form `parseRemote` reads is read as it does.
51
+ * A text that begins with `/`, `.` or `~`, a Windows drive or a `file:` URL is a path on this computer and an error, as it is there.
52
+ */
53
+ export declare function readRemote(input: string, hostKinds?: HostKinds): Result<ReadRemote, RemoteError>;
54
+ /** The HTTPS URL a repository is cloned from, with no credential in it. */
55
+ export declare function cloneUrlOf(ref: RepoRef): string;
56
+ /** A repository as `host/owner/repo`: the name used in messages, never a URL with a credential. */
57
+ export declare function describeRef(ref: RepoRef): string;
58
+ /** Whether two references name the same repository: the same host, and paths equal by their case (GitHub and GitLab paths are not case-sensitive). */
59
+ export declare function sameRepository(a: RepoRef, b: RepoRef): boolean;
@@ -0,0 +1,101 @@
1
+ import type { Result } from "@intellectual-frontiers/core";
2
+ /** The kinds of host: the keys of the code list `ifccm:GitManagerKind`, the one list of Git host kinds (`ifccm:hostedOn` ranges over it). */
3
+ export type HostKind = "Github" | "Gitlab" | "Git";
4
+ /** The capabilities a host may offer: the keys of the code list `ifccm:GitCapability`. */
5
+ export type Capability = "CloneUrl" | "Credentials" | "DefaultBranch" | "SignedCommits" | "ProtectedBranches" | "Issues" | "ChangeRequests" | "NestedGroups";
6
+ /** A repository on a host: the host name, and the path from it (owner then repository on GitHub; groups to any depth then repository on GitLab). Never contains a scheme or `.git`. */
7
+ export type RepoRef = {
8
+ readonly kind: HostKind;
9
+ /** The host name, such as `github.com`, `gitlab.com` or the name of a self-managed host. */
10
+ readonly host: string;
11
+ /** The path segments, the last being the repository. */
12
+ readonly path: readonly string[];
13
+ };
14
+ /** Whether a repository may be seen by anyone: `unknown` where the host was not asked or does not say. */
15
+ export type Visibility = "public" | "private" | "internal" | "unknown";
16
+ /** What a host says of a repository. */
17
+ export type RepoInfo = {
18
+ readonly ref: RepoRef;
19
+ readonly visibility: Visibility;
20
+ readonly defaultBranch: string;
21
+ /** The URL a clone is made from (HTTPS), without a credential in it. */
22
+ readonly cloneUrl: string;
23
+ readonly archived: boolean;
24
+ };
25
+ /** What a host says of an issue: the words and sections the change-control check reads. */
26
+ export type IssueInfo = {
27
+ /** The number the host gives it, in the repository (`#N` on GitHub, `#N` of a project on GitLab). */
28
+ readonly number: number;
29
+ readonly title: string;
30
+ readonly body: string;
31
+ readonly state: "open" | "closed";
32
+ readonly url: string;
33
+ /** The issue this one is a child of, where the host has parent and child issues. */
34
+ readonly parent?: number | undefined;
35
+ /** The issues that are children of this one, where the host has them. */
36
+ readonly children: readonly number[];
37
+ readonly labels: readonly string[];
38
+ /**
39
+ * Whether `parent` and `children` are the host's answer (`known`) or the host's API offers no parent and child issues, so that they are empty for want of an answer
40
+ * (`unavailable`: GitLab's REST API v4). Absent means `known`.
41
+ */
42
+ readonly hierarchy?: "known" | "unavailable" | undefined;
43
+ };
44
+ /** What a host says of a pull request or a merge request. */
45
+ export type ChangeRequestInfo = {
46
+ readonly number: number;
47
+ readonly title: string;
48
+ readonly state: "open" | "closed" | "merged";
49
+ readonly url: string;
50
+ readonly sourceBranch: string;
51
+ readonly targetBranch: string;
52
+ };
53
+ /** Whether a branch of a repository is protected (no push, no force, review required). */
54
+ export type BranchProtection = {
55
+ readonly branch: string;
56
+ readonly protected: boolean;
57
+ readonly requiresReview: boolean;
58
+ readonly allowsForcePush: boolean;
59
+ /**
60
+ * `protected-only` where the host says the branch is protected and the credential may not read the rules (GitHub shows them to administrators only), so that `requiresReview` and
61
+ * `allowsForcePush` are `false` for want of an answer, not by the host's word. Absent means `full`.
62
+ */
63
+ readonly detail?: "full" | "protected-only" | undefined;
64
+ };
65
+ /** Why a host did not answer. */
66
+ export type HostFailure = {
67
+ readonly kind: "unsupported";
68
+ readonly capability: Capability;
69
+ readonly host: HostKind;
70
+ } | {
71
+ readonly kind: "unauthorized";
72
+ readonly reason: string;
73
+ } | {
74
+ readonly kind: "not-found";
75
+ readonly what: string;
76
+ } | {
77
+ readonly kind: "rate-limited";
78
+ readonly retryAfterSeconds?: number | undefined;
79
+ } | {
80
+ readonly kind: "unreachable";
81
+ readonly reason: string;
82
+ } | {
83
+ readonly kind: "unexpected";
84
+ readonly status: number;
85
+ readonly reason: string;
86
+ };
87
+ /** An answer of a host. */
88
+ export type HostResult<T> = Result<T, HostFailure>;
89
+ /** The one interface to a host. Every method that a host may lack returns `unsupported` for it, and `capabilities` says which. */
90
+ export type GitHostClient = {
91
+ readonly kind: HostKind;
92
+ readonly capabilities: ReadonlySet<Capability>;
93
+ repository(ref: RepoRef): Promise<HostResult<RepoInfo>>;
94
+ issue(ref: RepoRef, number: number): Promise<HostResult<IssueInfo>>;
95
+ changeRequest(ref: RepoRef, number: number): Promise<HostResult<ChangeRequestInfo>>;
96
+ branchProtection(ref: RepoRef, branch: string): Promise<HostResult<BranchProtection>>;
97
+ /** Whether the commit's signature is verified by the host, where the host can say. */
98
+ commitVerified(ref: RepoRef, sha: string): Promise<HostResult<boolean>>;
99
+ };
100
+ /** The words of a failure, as a sentence for a finding. */
101
+ export declare function describeFailure(f: HostFailure): string;
@@ -0,0 +1,147 @@
1
+ /**
2
+ * Archives in memory, with no outside package (commons 0005-typescript-runtime FR-010). Writing: a POSIX ustar archive, a gzip stream of
3
+ * stored deflate blocks and a zip of stored entries (`zip`), each entry with a fixed time and mode and in the byte order of its path, so the
4
+ * bytes depend on the files alone (taken from erga's `lib/ts/archive`); and, where size matters more than the same bytes on every runtime,
5
+ * a zip of deflated entries (`zipDeflated`, through the web standard `CompressionStream`), the same bytes for the same files on one runtime
6
+ * and the same files unzipped on every runtime. Reading: a tar (ustar, pax and GNU long names), a gzip and a zip whose
7
+ * entries are stored or deflated (through the web standard `DecompressionStream`), each checked (header checksums, CRC-32) and every path
8
+ * refused that would leave the folder it is unpacked into. This is what lets Stolos drop `fflate` and unpack a verified copy of its engine.
9
+ * A tar, gzipped or not, is also read as a stream (`untarStream`, `readTarStream`), an entry at a time with each entry's bytes a stream of
10
+ * their own, with the same checks, so that an archive larger than memory can be read (FR-059).
11
+ *
12
+ * @example
13
+ * ```ts
14
+ * import { tar, untar, zip, unzip } from "./archive.js";
15
+ * const files = new Map([["a/b.txt", new TextEncoder().encode("hello")]]);
16
+ * const z = zip(files);
17
+ * const back = await unzip(z); // { kind: "ok", value: Map { "a/b.txt" => Uint8Array [104, 101, 108, 108, 111] } }
18
+ * ```
19
+ *
20
+ * @module
21
+ */
22
+ import { type Result } from "@intellectual-frontiers/core";
23
+ /** The files of an archive, by their path inside it. */
24
+ export type Files = ReadonlyMap<string, Uint8Array>;
25
+ /** Why an archive could not be read or written. */
26
+ export type ArchiveError = {
27
+ readonly kind: "damaged";
28
+ readonly message: string;
29
+ } | {
30
+ readonly kind: "unsupported";
31
+ readonly message: string;
32
+ } | {
33
+ readonly kind: "unsafe-path";
34
+ readonly path: string;
35
+ } | {
36
+ readonly kind: "too-long";
37
+ readonly path: string;
38
+ };
39
+ /** An archive error as one sentence. */
40
+ export declare function formatArchiveError(e: ArchiveError): string;
41
+ /** The CRC-32 (ISO 3309) that gzip and zip both carry. */
42
+ export declare function crc32(bytes: Uint8Array): number;
43
+ /**
44
+ * Whether a path inside an archive stays inside the folder it is unpacked into: relative, with `/` between its parts, no part `..`, no
45
+ * empty part but a trailing one, no backslash, no drive letter and no NUL.
46
+ */
47
+ export declare function isSafePath(path: string): boolean;
48
+ /** The paths of the files in the byte order of their UTF-8, the order every writer here uses. */
49
+ export declare function sortedPaths(paths: Iterable<string>): readonly string[];
50
+ /** Byte arrays joined end to end. */
51
+ export declare function concat(parts: readonly Uint8Array[]): Uint8Array;
52
+ /** A path too long for the 100 bytes of a ustar name, split into its prefix (up to 155 bytes) and name; undefined where it cannot be. */
53
+ export declare function splitName(path: string): readonly [string, string] | undefined;
54
+ /** One ustar header block of a file (mode 0644) or a folder (0755), owned by user 0, dated 0; undefined where the path does not fit. */
55
+ export declare function tarHeader(path: string, size: number, dir: boolean): Uint8Array | undefined;
56
+ /** A ustar archive of the files, each folder they lie in first given its own entry; or the path that does not fit or is not safe. */
57
+ export declare function tar(files: Files): Result<Uint8Array, ArchiveError>;
58
+ /** A gzip stream (RFC 1952) of the bytes in stored deflate blocks (RFC 1951 §3.2.4), with no name and no time: the same bytes every time. */
59
+ export declare function gzip(data: Uint8Array): Uint8Array;
60
+ /** A date as a zip writes it (MS-DOS): `(year - 1980) << 9 | month << 5 | day`. */
61
+ export declare function dosDate(year: number, month: number, day: number): number;
62
+ /** The zip's fixed date: 1980-01-01, the first a zip can hold. */
63
+ export declare const ZIP_EPOCH: number;
64
+ /** A zip (APPNOTE 6.3) of the files, each stored, dated `date` (1980-01-01 unless another is given) at midnight and readable by everyone. */
65
+ export declare function zip(files: Files, date?: number): Uint8Array;
66
+ /**
67
+ * A zip (APPNOTE 6.3) of the files as `zip` lays them out, but each entry deflated (method 8) through the web standard
68
+ * `CompressionStream("deflate-raw")`, or stored where deflating would not make it smaller (an empty or incompressible file). The bytes
69
+ * depend on the files alone on one runtime; another runtime's deflater may choose other (equally valid) bytes, so only what they unzip to
70
+ * is the same everywhere.
71
+ */
72
+ export declare function zipDeflated(files: Files, date?: number): Promise<Uint8Array>;
73
+ /** The raw deflate stream (RFC 1951) a web `CompressionStream` gives for the bytes. */
74
+ export declare function deflateRaw(data: Uint8Array): Promise<Uint8Array>;
75
+ /** The bytes of a gzip stream, stored or deflated, its CRC checked by the decompressor. */
76
+ export declare function gunzip(data: Uint8Array): Promise<Result<Uint8Array, ArchiveError>>;
77
+ /** One entry of a tar archive. A folder's path has no trailing `/`; a link's target is in `linkName`. */
78
+ export type TarEntry = {
79
+ readonly path: string;
80
+ readonly kind: "file" | "directory" | "symlink" | "hardlink";
81
+ readonly mode: number;
82
+ readonly data: Uint8Array;
83
+ readonly linkName: string;
84
+ };
85
+ /** The header of one entry of a tar archive: its path (a folder's with no trailing `/`), kind, mode, size of body, time and link target. */
86
+ export type TarHeader = {
87
+ readonly path: string;
88
+ readonly kind: TarEntry["kind"];
89
+ readonly mode: number;
90
+ readonly size: number;
91
+ /** Seconds since 1970, as the header (or a pax `mtime`) gives them. */
92
+ readonly mtime: number;
93
+ readonly linkName: string;
94
+ };
95
+ /** The entries of a tar archive (ustar, with pax extended headers and GNU long names), each header's checksum checked and each path checked safe. */
96
+ export declare function untar(data: Uint8Array): Result<readonly TarEntry[], ArchiveError>;
97
+ /** An archive error raised as an `Error`, which is how a stream reports one: the error itself is in `error`. */
98
+ export declare class ArchiveFailure extends Error {
99
+ /** Why the archive could not be read. */
100
+ readonly error: ArchiveError;
101
+ /** An `Error` for the archive error, its message the error's sentence. */
102
+ constructor(error: ArchiveError);
103
+ }
104
+ /**
105
+ * One entry of a tar archive read as a stream: its header and its body as a stream (empty but for a file). The body MUST be read to its
106
+ * end or cancelled before the next entry is given, as with `@std/tar`'s `UntarStream`.
107
+ */
108
+ export type TarStreamEntry = TarHeader & {
109
+ readonly readable: ReadableStream<Uint8Array>;
110
+ };
111
+ /**
112
+ * The entries of a tar archive given as a stream of bytes, gzipped or not (told by its first two bytes), one at a time as they are asked
113
+ * for, so that an archive larger than memory is read with one chunk held (commons 0005-typescript-runtime FR-059). Every header is checked
114
+ * as `untar` checks it (checksum, pax and GNU long names, a safe path); a failure errors the stream with an `ArchiveFailure`. Each entry's
115
+ * `readable` MUST be read to its end or cancelled before the next entry is given; cancelling the stream of entries cancels the bytes.
116
+ */
117
+ export declare function readTarStream(stream: ReadableStream<Uint8Array>): ReadableStream<TarStreamEntry>;
118
+ /**
119
+ * A stream from a tar archive's bytes, gzipped or not, to its entries, to put in a `pipeThrough` as `@std/tar`'s `UntarStream` is: see
120
+ * `readTarStream` for what it checks and how each entry's body is read (commons 0005-typescript-runtime FR-059).
121
+ *
122
+ * @example
123
+ * ```ts
124
+ * for await (const entry of file.readable.pipeThrough(untarStream())) {
125
+ * if (entry.path === "bin/tool") await save(entry.readable);
126
+ * else await entry.readable.cancel();
127
+ * }
128
+ * ```
129
+ */
130
+ export declare function untarStream(): ReadableWritablePair<TarStreamEntry, Uint8Array>;
131
+ /** The files of a list of tar entries, by path: folders and links left out. */
132
+ export declare function filesOf(entries: readonly TarEntry[]): Files;
133
+ /** One entry of a zip's central directory. */
134
+ export type ZipEntry = {
135
+ readonly name: string;
136
+ readonly method: number;
137
+ readonly crc: number;
138
+ readonly compressed: number;
139
+ readonly size: number;
140
+ readonly offset: number;
141
+ };
142
+ /** The entries of a zip, from its central directory; or why they cannot be read (a ZIP64 archive among the reasons). */
143
+ export declare function zipEntries(data: Uint8Array): Result<readonly ZipEntry[], ArchiveError>;
144
+ /** The bytes of one entry of a zip, stored (method 0) or deflated (method 8), its size and CRC-32 checked. */
145
+ export declare function zipRead(data: Uint8Array, e: ZipEntry): Promise<Result<Uint8Array, ArchiveError>>;
146
+ /** Every file of a zip by its path, folders left out, each read and checked, and every path checked safe. */
147
+ export declare function unzip(data: Uint8Array): Promise<Result<Files, ArchiveError>>;