@intellectual-frontiers/repoctl 0.0.0-stage → 0.1.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/LICENSE +75 -0
- package/README.md +19 -2
- package/dist/governance/checks.d.ts +23 -0
- package/dist/governance/config.d.ts +233 -0
- package/dist/governance/generators.d.ts +54 -0
- package/dist/governance/identity.d.ts +23 -0
- package/dist/governance/ids.d.ts +46 -0
- package/dist/governance/mod.d.ts +25 -0
- package/dist/governance/mod.js +1063 -0
- package/dist/governance/problems.d.ts +28 -0
- package/dist/governance/proof.d.ts +108 -0
- package/dist/governance/tiers.d.ts +25 -0
- package/dist/governance/verbs.d.ts +43 -0
- package/dist/governance/version.d.ts +14 -0
- package/dist/logical/check.d.ts +33 -0
- package/dist/logical/commit.d.ts +64 -0
- package/dist/logical/constants.d.ts +27 -0
- package/dist/logical/declared.d.ts +32 -0
- package/dist/logical/docs.d.ts +31 -0
- package/dist/logical/doctor.d.ts +42 -0
- package/dist/logical/findings.d.ts +26 -0
- package/dist/logical/glob.d.ts +17 -0
- package/dist/logical/hygiene-facts.d.ts +33 -0
- package/dist/logical/hygiene.d.ts +68 -0
- package/dist/logical/merge.d.ts +46 -0
- package/dist/logical/mod.d.ts +36 -0
- package/dist/logical/mod.js +2553 -0
- package/dist/logical/order.d.ts +24 -0
- package/dist/logical/pool.d.ts +14 -0
- package/dist/logical/ports.d.ts +96 -0
- package/dist/logical/prove.d.ts +118 -0
- package/dist/logical/publish.d.ts +70 -0
- package/dist/logical/scaffold.d.ts +52 -0
- package/dist/logical/select.d.ts +83 -0
- package/dist/logical/semver.d.ts +16 -0
- package/dist/logical/status.d.ts +71 -0
- package/dist/logical/step.d.ts +18 -0
- package/dist/logical/surface.d.ts +73 -0
- package/dist/logical/sync.d.ts +34 -0
- package/dist/mod.d.ts +20 -0
- package/dist/mod.js +12992 -0
- package/dist/physical/adapters.d.ts +25 -0
- package/dist/physical/config-load.d.ts +30 -0
- package/dist/physical/define.d.ts +73 -0
- package/dist/physical/mod.d.ts +26 -0
- package/dist/physical/mod.js +12660 -0
- package/dist/physical/program.d.ts +14 -0
- package/dist/physical/prove-run.d.ts +50 -0
- package/dist/physical/prove.d.ts +76 -0
- package/dist/physical/tests.d.ts +54 -0
- package/dist/physical/verbs/check.d.ts +26 -0
- package/dist/physical/verbs/docs.d.ts +6 -0
- package/dist/physical/verbs/library.d.ts +4 -0
- package/dist/physical/verbs/prove.d.ts +5 -0
- package/dist/physical/verbs/releasing.d.ts +27 -0
- package/dist/physical/verbs/sync.d.ts +12 -0
- package/dist/repoctl.d.ts +16 -0
- package/package.json +70 -4
- package/repoctl.mjs +12693 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
Required Notice: Copyright Intellectual Frontiers LLC (https://github.com/intellectual-frontiers/.github)
|
|
2
|
+
|
|
3
|
+
# PolyForm Noncommercial License 1.0.0
|
|
4
|
+
|
|
5
|
+
<https://polyformproject.org/licenses/noncommercial/1.0.0>
|
|
6
|
+
|
|
7
|
+
## Acceptance
|
|
8
|
+
|
|
9
|
+
In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
|
|
10
|
+
|
|
11
|
+
## Copyright License
|
|
12
|
+
|
|
13
|
+
The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
|
|
14
|
+
|
|
15
|
+
## Distribution License
|
|
16
|
+
|
|
17
|
+
The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
|
|
18
|
+
|
|
19
|
+
## Notices
|
|
20
|
+
|
|
21
|
+
You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
|
|
22
|
+
|
|
23
|
+
> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
|
|
24
|
+
|
|
25
|
+
## Changes and New Works License
|
|
26
|
+
|
|
27
|
+
The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
|
|
28
|
+
|
|
29
|
+
## Patent License
|
|
30
|
+
|
|
31
|
+
The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
|
|
32
|
+
|
|
33
|
+
## Noncommercial Purposes
|
|
34
|
+
|
|
35
|
+
Any noncommercial purpose is a permitted purpose.
|
|
36
|
+
|
|
37
|
+
## Personal Uses
|
|
38
|
+
|
|
39
|
+
Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
|
|
40
|
+
|
|
41
|
+
## Noncommercial Organizations
|
|
42
|
+
|
|
43
|
+
Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
|
|
44
|
+
|
|
45
|
+
## Fair Use
|
|
46
|
+
|
|
47
|
+
You may have "fair use" rights for the software under the law. These terms do not limit them.
|
|
48
|
+
|
|
49
|
+
## No Other Rights
|
|
50
|
+
|
|
51
|
+
These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
|
|
52
|
+
|
|
53
|
+
## Patent Defense
|
|
54
|
+
|
|
55
|
+
If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
|
|
56
|
+
|
|
57
|
+
## Violations
|
|
58
|
+
|
|
59
|
+
The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
|
|
60
|
+
|
|
61
|
+
## No Liability
|
|
62
|
+
|
|
63
|
+
***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
|
|
64
|
+
|
|
65
|
+
## Definitions
|
|
66
|
+
|
|
67
|
+
The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
|
|
68
|
+
|
|
69
|
+
**You** refers to the individual or entity agreeing to these terms.
|
|
70
|
+
|
|
71
|
+
**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
|
|
72
|
+
|
|
73
|
+
**Your licenses** are all the licenses granted to you for the software under these terms.
|
|
74
|
+
|
|
75
|
+
**Use** means anything you do with the software requiring one of your licenses.
|
package/README.md
CHANGED
|
@@ -1,3 +1,20 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Repoctl
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The operations program of a repository: one command, `repoctl`, driven by a typed `repoctl.config.ts` at the root of the repository it operates. It makes the generated files in dependency order and checks them, merges without hand-resolving a generated file, runs every named check in one calm report, makes the commit with the repository's identity and trailers, says what is wrong with a checkout, and, where the configuration turns them on, tells the version of each library, plans and publishes a release, scaffolds a library, proves a change by its blast radius and builds the documentation site.
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
npm install --save-dev @intellectual-frontiers/repoctl
|
|
7
|
+
npx repoctl doctor # what is wrong with this checkout, and the command for each
|
|
8
|
+
npx repoctl check # every check of the repository in one report, with codes for `repoctl explain`
|
|
9
|
+
npx repoctl sync --check # which generated files are stale
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
```ts
|
|
13
|
+
// repoctl.config.ts
|
|
14
|
+
import { defineConfig } from "@intellectual-frontiers/repoctl";
|
|
15
|
+
export default defineConfig({ repo: "acme/app", commit: { identity: { name: "A B", email: "a@example.test" }, issue: { prefix: "Refs #" } } });
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Every verb says what it may change (`--dry-run` shows it, `--check` checks it, `--yes` confirms a destruction), writes its report on standard output and its problems and the one `next:` command on standard error, and ends in the statuses 0 ok, 1 findings, 2 usage, 3 environment. `repoctl mcp` serves the verbs as tools of a tool server, by the audience tier the host holds (`REPOCTL_TIER`: public, contributor, releaser). `repoctl docs` needs `@intellectual-frontiers/docs`, an optional peer.
|
|
19
|
+
|
|
20
|
+
The sources and the specifications are in https://github.com/intellectual-frontiers/.github/tree/main/commons/repoctl
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The checks of `repoctl check` that are not generators, declared in a repository's configuration as data (commons repoctl 0002-repoctl-governance FR-006; 0009-repoctl-config FR-003): a named program that judges the repository, the sentence that
|
|
3
|
+
* names it and the problem code a finding of it is reported with. The checks of the generated files are the generators' own (`generators.ts`).
|
|
4
|
+
*
|
|
5
|
+
* @example
|
|
6
|
+
* ```ts
|
|
7
|
+
* import type { Check } from "./checks.js";
|
|
8
|
+
* const c: Pick<Check, "code"> = { code: "E-CHECK-FAILED" };
|
|
9
|
+
* c.code; // "E-CHECK-FAILED"
|
|
10
|
+
* ```
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
import type { StepId } from "./ids.js";
|
|
15
|
+
import type { ProblemCode } from "./problems.js";
|
|
16
|
+
import type { Step } from "./generators.js";
|
|
17
|
+
/** A check: the program (or typed function), the code of its findings. It ends with 0 where nothing is wrong, with 1 where something is, and its lines are the findings. */
|
|
18
|
+
export type Check = {
|
|
19
|
+
readonly id: StepId;
|
|
20
|
+
readonly summary: string;
|
|
21
|
+
readonly run: Step;
|
|
22
|
+
readonly code: ProblemCode;
|
|
23
|
+
};
|
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The configuration of a repository (commons repoctl 0009-repoctl-config FR-001 to FR-006): `repoctl.config.ts` at the repository's root says everything `repoctl` knows of the repository it operates, as typed data. `defineConfig` is
|
|
3
|
+
* the one way a configuration is written (it checks the shape and is the identity); `parseConfig` is the one way the host reads one (it makes every identity by its smart constructor and says every reason a configuration is wrong, at once).
|
|
4
|
+
* Nothing about any repository is in the host: the generators, the checks, the commit rules, the hygiene policy, the doctor's pins, the names of the variables and the optional verbs are all here.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```ts
|
|
8
|
+
* import { defineConfig, parseConfig } from "./config.js";
|
|
9
|
+
* const input = defineConfig({
|
|
10
|
+
* repo: "app",
|
|
11
|
+
* commit: { identity: { name: "A B", email: "a@example.test" }, issue: { prefix: "Refs #", required: false }, trailers: ["issue"] },
|
|
12
|
+
* });
|
|
13
|
+
* parseConfig(input).kind; // "ok"
|
|
14
|
+
* ```
|
|
15
|
+
*
|
|
16
|
+
* @module
|
|
17
|
+
*/
|
|
18
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
19
|
+
import type { Check } from "./checks.js";
|
|
20
|
+
import type { Generator, StepFunction } from "./generators.js";
|
|
21
|
+
import { type Identity } from "./identity.js";
|
|
22
|
+
import { type VariableName } from "./ids.js";
|
|
23
|
+
import { type ProblemCode } from "./problems.js";
|
|
24
|
+
import type { VerbId } from "./verbs.js";
|
|
25
|
+
/** The trailers a commit may carry, in the order a configuration lists them: the reference to an issue, the line that credits the agent and the address of the session. */
|
|
26
|
+
export type TrailerKind = "issue" | "co-author" | "session";
|
|
27
|
+
/** Every trailer, in the order of the documentation. */
|
|
28
|
+
export declare const TRAILER_KINDS: readonly TrailerKind[];
|
|
29
|
+
/** A path that must not be committed, by a glob from the repository's root, and the reason said to the person. */
|
|
30
|
+
export type ForbiddenPath = {
|
|
31
|
+
readonly glob: string;
|
|
32
|
+
readonly why: string;
|
|
33
|
+
};
|
|
34
|
+
/** A text that looks like a secret: a regular expression's source and what it looks like. */
|
|
35
|
+
export type SecretPattern = {
|
|
36
|
+
readonly pattern: string;
|
|
37
|
+
readonly label: string;
|
|
38
|
+
};
|
|
39
|
+
/** The rules of `repoctl commit`. */
|
|
40
|
+
export type CommitPolicy = {
|
|
41
|
+
/** The author and the committer of every commit. */
|
|
42
|
+
readonly identity: Identity;
|
|
43
|
+
/** The reference to an issue: the line is the prefix and the number (`Refs #` and `10` make `Refs #10`); `required` makes `--refs` mandatory. */
|
|
44
|
+
readonly issue: {
|
|
45
|
+
readonly prefix: string;
|
|
46
|
+
readonly required: boolean;
|
|
47
|
+
};
|
|
48
|
+
/** The trailers after the subject, in order. The line that credits the agent comes from `--co-author` or `REPOCTL_CO_AUTHOR` (else `coAuthor`), the session from `--session` or `CLAUDE_SESSION_URL`. */
|
|
49
|
+
readonly trailers: readonly TrailerKind[];
|
|
50
|
+
/** The line that credits the agent where neither the command line nor the environment gives one. */
|
|
51
|
+
readonly coAuthor: string | undefined;
|
|
52
|
+
readonly forbidden: {
|
|
53
|
+
readonly paths: readonly ForbiddenPath[];
|
|
54
|
+
/** Globs of paths that are allowed though a forbidden glob matches them. */
|
|
55
|
+
readonly allow: readonly string[];
|
|
56
|
+
readonly secrets: readonly SecretPattern[];
|
|
57
|
+
};
|
|
58
|
+
};
|
|
59
|
+
/** The policy of `repoctl hygiene`: how a repository may consume the packages of a family. */
|
|
60
|
+
export type HygienePolicy = {
|
|
61
|
+
/** The scope of the packages that are the family's (`@scope/`). */
|
|
62
|
+
readonly scope: string;
|
|
63
|
+
/** Fragments (lower case) of a Git dependency's specifier that name the family's own repository. */
|
|
64
|
+
readonly gitSources: readonly string[];
|
|
65
|
+
/** A folder name that a `file:` or `link:` dependency or a relative import must not go through. */
|
|
66
|
+
readonly pathSegment: string;
|
|
67
|
+
/** The file whose presence says this repository is the family's own, where the path, import and vendored findings are not made. */
|
|
68
|
+
readonly sourceMarker: string;
|
|
69
|
+
/** Allowances: globs of dependency paths that may be linked, and package names that may be carried by a folder of the repository. */
|
|
70
|
+
readonly allow: {
|
|
71
|
+
readonly paths: readonly string[];
|
|
72
|
+
readonly packages: readonly string[];
|
|
73
|
+
};
|
|
74
|
+
};
|
|
75
|
+
/** What `repoctl doctor` checks of a checkout besides Git and the generated files. */
|
|
76
|
+
export type DoctorPolicy = {
|
|
77
|
+
/** The least major version of Node, or none where the repository has no rule. */
|
|
78
|
+
readonly minNode: number | undefined;
|
|
79
|
+
/** The file (from the root) that pins the version of Bun and the variable in it, or none. */
|
|
80
|
+
readonly bunPin: {
|
|
81
|
+
readonly file: string;
|
|
82
|
+
readonly variable: string;
|
|
83
|
+
} | undefined;
|
|
84
|
+
/** The folder (from the root) under which the libraries are linked, and the program that links them, or none. */
|
|
85
|
+
readonly links: {
|
|
86
|
+
readonly folder: string;
|
|
87
|
+
readonly fix: readonly string[];
|
|
88
|
+
} | undefined;
|
|
89
|
+
/** What to run to install the dependencies, said in the finding. */
|
|
90
|
+
readonly install: string;
|
|
91
|
+
};
|
|
92
|
+
/** The settings of the verbs that know a family of libraries (status, release, new library, prove). */
|
|
93
|
+
export type LibrariesSettings = {
|
|
94
|
+
/** The folder (from the root) whose subfolders are the libraries, each with a `library.ts` manifest. */
|
|
95
|
+
readonly folder: string;
|
|
96
|
+
/** The program that judges the specification kit of a library: the words `{kit}` and `{level}` are replaced by its folder and level. */
|
|
97
|
+
readonly specKit: {
|
|
98
|
+
readonly format: readonly string[];
|
|
99
|
+
readonly rules: readonly string[];
|
|
100
|
+
} | undefined;
|
|
101
|
+
/** Whether a source that says a library's version in a constant is checked against the manifest. */
|
|
102
|
+
readonly versionConstants: boolean;
|
|
103
|
+
/** Whether every package a library imports is declared in its manifest (a library job installs only its own folder). */
|
|
104
|
+
readonly declaredDependencies: boolean;
|
|
105
|
+
/** The program that links the libraries under the folder before a verb imports one, or none. */
|
|
106
|
+
readonly linker: readonly string[] | undefined;
|
|
107
|
+
/** The source (from the root) that classifies each library by role, which `new library` edits to add the new one; none where the repository has no such file. */
|
|
108
|
+
readonly roleFile: string | undefined;
|
|
109
|
+
};
|
|
110
|
+
/** The optional verbs a repository turns on. */
|
|
111
|
+
export type Capabilities = {
|
|
112
|
+
/** `release plan`, `release apply` and `release publish`: only for a repository with library manifests. */
|
|
113
|
+
readonly release: boolean;
|
|
114
|
+
/** `new library`. */
|
|
115
|
+
readonly newLibrary: boolean;
|
|
116
|
+
/** `status` of the packages. */
|
|
117
|
+
readonly status: boolean;
|
|
118
|
+
/** `prove`, the proof of a change by its blast radius. */
|
|
119
|
+
readonly prove: boolean;
|
|
120
|
+
};
|
|
121
|
+
/** The documentation generator's settings: its configuration file and the folder the site is built into, from the root, and the module (from the root) that is the generator where it is a source of the repository and not an installed package. */
|
|
122
|
+
export type DocsSettings = {
|
|
123
|
+
readonly config: string;
|
|
124
|
+
readonly out: string;
|
|
125
|
+
readonly generator: string | undefined;
|
|
126
|
+
};
|
|
127
|
+
/** A configuration, as the host reads it: every identity made, every default filled. */
|
|
128
|
+
export type Config = {
|
|
129
|
+
readonly repo: string;
|
|
130
|
+
/** The variable that says which tier the host holds, and the one that says a tool server may only read. */
|
|
131
|
+
readonly tierVariable: VariableName;
|
|
132
|
+
readonly readOnlyVariable: VariableName;
|
|
133
|
+
readonly commit: CommitPolicy;
|
|
134
|
+
readonly generators: readonly Generator[];
|
|
135
|
+
readonly checks: readonly Check[];
|
|
136
|
+
readonly capabilities: Capabilities;
|
|
137
|
+
readonly libraries: LibrariesSettings | undefined;
|
|
138
|
+
readonly hygiene: HygienePolicy | undefined;
|
|
139
|
+
readonly doctor: DoctorPolicy;
|
|
140
|
+
readonly docs: DocsSettings | undefined;
|
|
141
|
+
};
|
|
142
|
+
/** A program or a typed function, as a configuration writes it. */
|
|
143
|
+
export type StepInput = readonly string[] | StepFunction;
|
|
144
|
+
/** A generator, as a configuration writes it: the check is the program with `--check` added where it is not given. */
|
|
145
|
+
export type GeneratorInput = {
|
|
146
|
+
readonly id: string;
|
|
147
|
+
readonly summary?: string;
|
|
148
|
+
readonly command: StepInput;
|
|
149
|
+
readonly check?: StepInput;
|
|
150
|
+
readonly inputs?: readonly string[];
|
|
151
|
+
readonly outputs: readonly string[];
|
|
152
|
+
readonly after?: readonly string[];
|
|
153
|
+
readonly mixed?: readonly string[];
|
|
154
|
+
};
|
|
155
|
+
/** A check, as a configuration writes it. */
|
|
156
|
+
export type CheckInput = {
|
|
157
|
+
readonly id: string;
|
|
158
|
+
readonly summary?: string;
|
|
159
|
+
readonly command: StepInput;
|
|
160
|
+
readonly code?: ProblemCode;
|
|
161
|
+
};
|
|
162
|
+
/** A configuration as it is written in `repoctl.config.ts`: what it leaves out has the default the documentation says. */
|
|
163
|
+
export type ConfigInput = {
|
|
164
|
+
readonly repo: string;
|
|
165
|
+
readonly tierVariable?: string;
|
|
166
|
+
readonly readOnlyVariable?: string;
|
|
167
|
+
readonly commit: {
|
|
168
|
+
readonly identity: Identity;
|
|
169
|
+
readonly issue?: {
|
|
170
|
+
readonly prefix: string;
|
|
171
|
+
readonly required?: boolean;
|
|
172
|
+
};
|
|
173
|
+
readonly trailers?: readonly TrailerKind[];
|
|
174
|
+
readonly coAuthor?: string;
|
|
175
|
+
readonly forbidden?: {
|
|
176
|
+
readonly paths?: readonly ForbiddenPath[];
|
|
177
|
+
readonly allow?: readonly string[];
|
|
178
|
+
readonly secrets?: readonly SecretPattern[];
|
|
179
|
+
};
|
|
180
|
+
};
|
|
181
|
+
readonly generators?: readonly GeneratorInput[];
|
|
182
|
+
readonly checks?: readonly CheckInput[];
|
|
183
|
+
readonly capabilities?: Partial<Capabilities>;
|
|
184
|
+
readonly libraries?: {
|
|
185
|
+
readonly folder: string;
|
|
186
|
+
readonly specKit?: LibrariesSettings["specKit"];
|
|
187
|
+
readonly versionConstants?: boolean;
|
|
188
|
+
readonly declaredDependencies?: boolean;
|
|
189
|
+
readonly linker?: readonly string[];
|
|
190
|
+
readonly roleFile?: string;
|
|
191
|
+
};
|
|
192
|
+
readonly hygiene?: {
|
|
193
|
+
readonly scope: string;
|
|
194
|
+
readonly gitSources?: readonly string[];
|
|
195
|
+
readonly pathSegment?: string;
|
|
196
|
+
readonly sourceMarker?: string;
|
|
197
|
+
readonly allow?: {
|
|
198
|
+
readonly paths?: readonly string[];
|
|
199
|
+
readonly packages?: readonly string[];
|
|
200
|
+
};
|
|
201
|
+
};
|
|
202
|
+
readonly doctor?: {
|
|
203
|
+
readonly minNode?: number;
|
|
204
|
+
readonly bunPin?: DoctorPolicy["bunPin"];
|
|
205
|
+
readonly links?: DoctorPolicy["links"];
|
|
206
|
+
readonly install?: string;
|
|
207
|
+
};
|
|
208
|
+
readonly docs?: {
|
|
209
|
+
readonly config?: string;
|
|
210
|
+
readonly out?: string;
|
|
211
|
+
readonly generator?: string;
|
|
212
|
+
};
|
|
213
|
+
};
|
|
214
|
+
/** The names of the optional verbs a configuration turns on with a flag. */
|
|
215
|
+
export declare const CAPABILITY_NAMES: readonly (keyof Capabilities)[];
|
|
216
|
+
/** The name of the file a repository keeps its configuration in, at its root. */
|
|
217
|
+
export declare const CONFIG_FILE = "repoctl.config.ts";
|
|
218
|
+
/** The variable that fixes the tier the host holds, where a configuration does not name another. */
|
|
219
|
+
export declare const DEFAULT_TIER_VARIABLE = "REPOCTL_TIER";
|
|
220
|
+
/** The variable that says the key of a tool server may only read, where a configuration does not name another. */
|
|
221
|
+
export declare const DEFAULT_READ_ONLY_VARIABLE = "REPOCTL_READ_ONLY";
|
|
222
|
+
/** The paths no repository commits: the local folder of an agent, installed packages, files that hold secrets. A configuration spreads or replaces it. */
|
|
223
|
+
export declare const DEFAULT_FORBIDDEN_PATHS: readonly ForbiddenPath[];
|
|
224
|
+
/** The environment files that are examples and are committed. */
|
|
225
|
+
export declare const DEFAULT_ALLOWED_PATHS: readonly string[];
|
|
226
|
+
/** The texts that look like secrets: the keys and tokens of the common services. */
|
|
227
|
+
export declare const DEFAULT_SECRET_PATTERNS: readonly SecretPattern[];
|
|
228
|
+
/** A configuration, written: the identity that checks its shape. */
|
|
229
|
+
export declare function defineConfig(input: ConfigInput): ConfigInput;
|
|
230
|
+
/** The configuration as the host reads it, or every reason it is wrong. */
|
|
231
|
+
export declare function parseConfig(input: ConfigInput): Result<Config, readonly string[]>;
|
|
232
|
+
/** The verbs a configuration turns on besides the ones every repository has (check, sync, merge, commit, doctor): each capability adds its own. */
|
|
233
|
+
export declare function enabledVerbs(config: Config): readonly VerbId[];
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The generators of a repository, declared in its configuration as data (commons repoctl 0002-repoctl-governance FR-005; 0009-repoctl-config FR-003): each is a program (or a typed function) that makes files from sources and checks that they are what
|
|
3
|
+
* it makes, with the globs of what it reads and of what it writes and the generators it declares to come after. `repoctl sync` runs them in the order those facts give, `repoctl merge` knows a generated file by them and `repoctl check` runs each one's check.
|
|
4
|
+
*
|
|
5
|
+
* @example
|
|
6
|
+
* ```ts
|
|
7
|
+
* import type { Generator } from "./generators.js";
|
|
8
|
+
* const g: Pick<Generator, "outputs"> = { outputs: ["README.md"] };
|
|
9
|
+
* g.outputs; // ["README.md"]
|
|
10
|
+
* ```
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
import type { StepId } from "./ids.js";
|
|
15
|
+
/** How a step ended: the status (0 it is as it should be, 1 it is not, anything else it could not run) and what it said. */
|
|
16
|
+
export type StepRun = {
|
|
17
|
+
readonly code: number;
|
|
18
|
+
readonly stdout: string;
|
|
19
|
+
readonly stderr: string;
|
|
20
|
+
};
|
|
21
|
+
/** What a typed step is given: the repository's root, as an absolute path. */
|
|
22
|
+
export type StepContext = {
|
|
23
|
+
readonly repo: string;
|
|
24
|
+
};
|
|
25
|
+
/** A step that is a typed function in the configuration, in place of a program. */
|
|
26
|
+
export type StepFunction = (context: StepContext) => Promise<StepRun>;
|
|
27
|
+
/** A step: the argument vector of a program run from the repository's root (no shell between), or a typed function. */
|
|
28
|
+
export type Step = {
|
|
29
|
+
readonly kind: "program";
|
|
30
|
+
readonly argv: readonly string[];
|
|
31
|
+
} | {
|
|
32
|
+
readonly kind: "function";
|
|
33
|
+
readonly call: StepFunction;
|
|
34
|
+
readonly label: string;
|
|
35
|
+
};
|
|
36
|
+
/** A generator: what it is, how it makes its files and checks them, and what it reads and writes. */
|
|
37
|
+
export type Generator = {
|
|
38
|
+
readonly id: StepId;
|
|
39
|
+
readonly summary: string;
|
|
40
|
+
/** Makes the files. */
|
|
41
|
+
readonly run: Step;
|
|
42
|
+
/** Writes nothing and ends with 0 where the files are what `run` makes and with 1 where they are not. */
|
|
43
|
+
readonly check: Step;
|
|
44
|
+
/** What it reads, as globs from the repository's root (`*` is one segment's characters, `**` any number of segments). */
|
|
45
|
+
readonly inputs: readonly string[];
|
|
46
|
+
/** What it writes, as globs from the repository's root. */
|
|
47
|
+
readonly outputs: readonly string[];
|
|
48
|
+
/** The generators it comes after, besides those whose outputs it reads. */
|
|
49
|
+
readonly after: readonly StepId[];
|
|
50
|
+
/** The outputs (globs, a subset of `outputs`) that also hold text a person wrote and that the generator leaves as it finds it, so that a merge keeps the lines of both sides of them before it makes the generated part again. */
|
|
51
|
+
readonly mixed: readonly string[];
|
|
52
|
+
};
|
|
53
|
+
/** The command that makes a step's files again, as a person types it. */
|
|
54
|
+
export declare function stepText(step: Step): string;
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The names a commit of any repository shares (commons repoctl 0005-repoctl-library-commit-doctor FR-004, FR-005; 0009-repoctl-config FR-004): the variable that holds the address of the session and the arguments of `git` that make a commit as
|
|
3
|
+
* the identity a repository's configuration names. The identity itself, the trailers and the issue reference are the repository's, in its `repoctl.config.ts`; nothing about one repository is here.
|
|
4
|
+
*
|
|
5
|
+
* @example
|
|
6
|
+
* ```ts
|
|
7
|
+
* import { identityArgs } from "./identity.js";
|
|
8
|
+
* identityArgs({ name: "A B", email: "a@example.test" }); // ["-c", "user.name=A B", "-c", "user.email=a@example.test"]
|
|
9
|
+
* ```
|
|
10
|
+
*
|
|
11
|
+
* @module
|
|
12
|
+
*/
|
|
13
|
+
/** The name and the address a commit is made with. */
|
|
14
|
+
export type Identity = {
|
|
15
|
+
readonly name: string;
|
|
16
|
+
readonly email: string;
|
|
17
|
+
};
|
|
18
|
+
/** The environment variable that holds the address of the session. */
|
|
19
|
+
export declare const SESSION_VARIABLE = "CLAUDE_SESSION_URL";
|
|
20
|
+
/** The environment variable that holds the line that credits the agent, where the command line does not give `--co-author`. */
|
|
21
|
+
export declare const CO_AUTHOR_VARIABLE = "REPOCTL_CO_AUTHOR";
|
|
22
|
+
/** The arguments of `git` that make the commit as the identity, whatever the checkout's own configuration says. */
|
|
23
|
+
export declare function identityArgs(identity: Identity): readonly string[];
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The identities of Repoctl as types that cannot be made wrong (commons repoctl 0002-repoctl-governance FR-001): a library name, a version, an issue number, a session address, a commit subject and a Git reference are values
|
|
3
|
+
* of a branded type, each made only by its smart constructor, which says why a text is not one. A function that takes one never checks again.
|
|
4
|
+
*
|
|
5
|
+
* @example
|
|
6
|
+
* ```ts
|
|
7
|
+
* import { parseLibraryName, parseSemver } from "./ids.js";
|
|
8
|
+
* parseLibraryName("repoctl").kind; // "ok"
|
|
9
|
+
* parseSemver("1.2").kind; // "err"
|
|
10
|
+
* ```
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
import { type Brand, type Result } from "@intellectual-frontiers/core";
|
|
15
|
+
/** The name of a library of commons: its folder and the end of its package name. */
|
|
16
|
+
export type LibraryName = Brand<string, "library name">;
|
|
17
|
+
/** A version of Semantic Versioning, with an optional pre-release and build part. */
|
|
18
|
+
export type Semver = Brand<string, "semver">;
|
|
19
|
+
/** The number of an issue of the repository, in digits. */
|
|
20
|
+
export type IssueNumber = Brand<string, "issue number">;
|
|
21
|
+
/** The address of a Claude Code session: https, with a host and no credential. */
|
|
22
|
+
export type SessionUrl = Brand<string, "session url">;
|
|
23
|
+
/** The subject line of a commit: one line of at most 100 characters that does not end with a full stop. */
|
|
24
|
+
export type CommitSubject = Brand<string, "commit subject">;
|
|
25
|
+
/** A name Git accepts for a branch, a tag or a remote reference, which does not begin with a dash. */
|
|
26
|
+
export type GitRef = Brand<string, "git ref">;
|
|
27
|
+
/** The name of a generator or of a check of a repository's configuration: lower-case words, digits, hyphens and colons. */
|
|
28
|
+
export type StepId = Brand<string, "step id">;
|
|
29
|
+
/** The name of an environment variable: capitals, digits and underscores, not starting with a digit. */
|
|
30
|
+
export type VariableName = Brand<string, "variable name">;
|
|
31
|
+
/** A library name from text, or why the text is not one. */
|
|
32
|
+
export declare function parseLibraryName(text: string): Result<LibraryName, string>;
|
|
33
|
+
/** A version from text, or why the text is not one. */
|
|
34
|
+
export declare function parseSemver(text: string): Result<Semver, string>;
|
|
35
|
+
/** An issue number from text (`10` or `#10`), or why the text is not one. */
|
|
36
|
+
export declare function parseIssueNumber(text: string): Result<IssueNumber, string>;
|
|
37
|
+
/** A session address from text, or why the text is not one. */
|
|
38
|
+
export declare function parseSessionUrl(text: string): Result<SessionUrl, string>;
|
|
39
|
+
/** A commit subject from text, or why the text is not one. */
|
|
40
|
+
export declare function parseSubject(text: string): Result<CommitSubject, string>;
|
|
41
|
+
/** A Git reference from text, or why the text is not one. */
|
|
42
|
+
export declare function parseGitRef(text: string): Result<GitRef, string>;
|
|
43
|
+
/** The name of a generator or of a check from text, or why the text is not one. */
|
|
44
|
+
export declare function parseStepId(text: string): Result<StepId, string>;
|
|
45
|
+
/** The name of an environment variable from text, or why the text is not one. */
|
|
46
|
+
export declare function parseVariableName(text: string): Result<VariableName, string>;
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Governance layer of Repoctl (commons repoctl 0002-repoctl-governance): what the program is, as data and as types that cannot be made wrong, before any surface draws it: the identities (a library, a version, an issue,
|
|
3
|
+
* a session, a subject), the audience tiers, the verbs with their facts and reach, the problem codes with their explanations, the configuration of a repository (its generators, checks, commit rules and optional verbs). It imports Core and the governance of Headless alone and
|
|
4
|
+
* does no input or output.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```ts
|
|
8
|
+
* import { VERBS, defineConfig, parseLibraryName } from "@intellectual-frontiers/repoctl/governance";
|
|
9
|
+
* VERBS.sync.tier; // "contributor"
|
|
10
|
+
* typeof defineConfig; // "function"
|
|
11
|
+
* parseLibraryName("repoctl").kind; // "ok"
|
|
12
|
+
* ```
|
|
13
|
+
*
|
|
14
|
+
* @module
|
|
15
|
+
*/
|
|
16
|
+
export * from "./checks.js";
|
|
17
|
+
export * from "./config.js";
|
|
18
|
+
export * from "./generators.js";
|
|
19
|
+
export * from "./identity.js";
|
|
20
|
+
export * from "./ids.js";
|
|
21
|
+
export * from "./problems.js";
|
|
22
|
+
export * from "./proof.js";
|
|
23
|
+
export * from "./tiers.js";
|
|
24
|
+
export * from "./verbs.js";
|
|
25
|
+
export * from "./version.js";
|