@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
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import type { Config } from "@intellectual-frontiers/repoctl/governance";
|
|
2
|
+
import type { Credentials, DocsPort, Files, Libraries, Process, Registry, World } from "@intellectual-frontiers/repoctl/logical";
|
|
3
|
+
/** The variable that holds the token for npm. */
|
|
4
|
+
export declare const NPM_TOKEN_VARIABLE = "INFRO_NPMJS_TOKEN";
|
|
5
|
+
/** Programs run through the system, with the environment this process has plus what a run adds. */
|
|
6
|
+
export declare const systemProcess: Process;
|
|
7
|
+
/** Files on the system's disk. */
|
|
8
|
+
export declare const systemFiles: Files;
|
|
9
|
+
/** What the registry of npm says of a package: its latest version and the versions it lists. */
|
|
10
|
+
export declare const npmRegistry: Registry;
|
|
11
|
+
/** The credentials a host holds, read from its environment by name: the token for npm. */
|
|
12
|
+
export declare function envCredentials(env: (name: string) => string | undefined): Credentials;
|
|
13
|
+
/** The libraries of the repository, read from their manifests; none where its configuration has no libraries. */
|
|
14
|
+
export declare function manifestLibraries(repo: string, configured: boolean): Libraries;
|
|
15
|
+
/** The package of the documentation generator, which `repoctl docs` loads where it is installed. */
|
|
16
|
+
export declare const DOCS_PACKAGE = "@intellectual-frontiers/docs";
|
|
17
|
+
/** The documentation generator: the package found in the `node_modules` of the repository or above it (an optional peer of this program, never carried by it). */
|
|
18
|
+
export declare const systemDocs: DocsPort;
|
|
19
|
+
/** A folder served on a loopback port (0 asks the system for one): the address and the function that stops it. Nothing leaves the computer: the socket is bound to 127.0.0.1. */
|
|
20
|
+
export declare function serveFolder(folder: string, port: number): Promise<{
|
|
21
|
+
readonly url: string;
|
|
22
|
+
readonly close: () => Promise<void>;
|
|
23
|
+
}>;
|
|
24
|
+
/** The world of a repository on this system: every port filled. */
|
|
25
|
+
export declare function systemWorld(repo: string, env: (name: string) => string | undefined, config: Pick<Config, "libraries">): World;
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* How the host finds and loads a repository's configuration (commons repoctl 0009-repoctl-config FR-002): `--config FILE`, else the first `repoctl.config.ts` from the working folder up to the root of the Git checkout; the file is imported (it
|
|
3
|
+
* runs on Bun and on Node 26 as it is), its default export, or its export `config`, is read by `parseConfig`, and every way it can fail is a typed problem with its code. The repository's root is the folder of the file.
|
|
4
|
+
*
|
|
5
|
+
* @example
|
|
6
|
+
* ```ts
|
|
7
|
+
* import { findConfigFile } from "@intellectual-frontiers/repoctl/physical";
|
|
8
|
+
* findConfigFile("/nowhere/at/all", undefined); // undefined
|
|
9
|
+
* ```
|
|
10
|
+
*
|
|
11
|
+
* @module
|
|
12
|
+
*/
|
|
13
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
14
|
+
import { type Config } from "@intellectual-frontiers/repoctl/governance";
|
|
15
|
+
/** Why a configuration could not be had. */
|
|
16
|
+
export type ConfigProblem = {
|
|
17
|
+
readonly code: "E-CONFIG-MISSING" | "E-CONFIG-LOAD" | "E-CONFIG-INVALID";
|
|
18
|
+
readonly message: string;
|
|
19
|
+
};
|
|
20
|
+
/** The configuration's file: the one `--config` names, else the first `repoctl.config.ts` from a folder up to the root of the checkout (the first folder that holds `.git`, which is searched too). */
|
|
21
|
+
export declare function findConfigFile(from: string, explicit: string | undefined): string | undefined;
|
|
22
|
+
/** Loads a configuration file: its root (the folder it is in) and the configuration, or the problem. */
|
|
23
|
+
export declare function loadConfigFile(file: string): Promise<Result<{
|
|
24
|
+
readonly root: string;
|
|
25
|
+
readonly config: Config;
|
|
26
|
+
}, ConfigProblem>>;
|
|
27
|
+
/** The configuration of no repository: no generator, no check, no optional verb. What a host holds where the file is missing, so that `help` and `doctor` still run. */
|
|
28
|
+
export declare function bareConfig(): Config;
|
|
29
|
+
/** The configuration of an imagined repository that has every optional verb, which is what a documentation lens describes: the program is described with all of its verbs. */
|
|
30
|
+
export declare function describedConfig(): Config;
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* How a verb of `repoctl` is declared on Headless (commons repoctl 0006-repoctl-surfaces FR-001, FR-004; commons headless 0003-headless-output, 0004-headless-cli): a verb is declared once with its words, options, operands and examples, and its
|
|
3
|
+
* action's traits come from the facts table of Governance (`VERBS`), so that what the command line, the tool server and the documentation say of it is one fact. The body returns the findings and the data of the run; this turns them into
|
|
4
|
+
* Headless' outcome, with the code and the fix of each finding as the problem it is.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```ts
|
|
8
|
+
* import { traitsOf } from "@intellectual-frontiers/repoctl/physical";
|
|
9
|
+
* traitsOf("release publish").reach?.confirmation; // "person"
|
|
10
|
+
* ```
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
import { type Problem } from "@intellectual-frontiers/headless/governance";
|
|
15
|
+
import { type ActionTraits, type Command, type Context, type Outcome } from "@intellectual-frontiers/headless/logical";
|
|
16
|
+
import type { Args, Operand, Spec, SpecCheck } from "@intellectual-frontiers/terminal/args";
|
|
17
|
+
import type { Example } from "@intellectual-frontiers/terminal/commands";
|
|
18
|
+
import { type VerbId } from "@intellectual-frontiers/repoctl/governance";
|
|
19
|
+
import type { Finding, World } from "@intellectual-frontiers/repoctl/logical";
|
|
20
|
+
import type { Result } from "@intellectual-frontiers/core";
|
|
21
|
+
import type { Host as ReleasingHost } from "@intellectual-frontiers/libraries/releasing";
|
|
22
|
+
import type { Config, Generator } from "@intellectual-frontiers/repoctl/governance";
|
|
23
|
+
/** What the program holds for every run of its verbs: the environment, and the world, made where it is needed (it needs the repository's root, which a documentation lens has not got). */
|
|
24
|
+
export type Host = {
|
|
25
|
+
readonly env: (name: string) => string | undefined;
|
|
26
|
+
readonly world: () => Result<World, string>;
|
|
27
|
+
/** The repository's configuration, read and checked: everything the verbs know of it. Where there is none (or it is wrong) it is the bare one and `configProblem` says why. */
|
|
28
|
+
readonly config: Config;
|
|
29
|
+
/** Why the configuration could not be had: a verb that needs it ends with this, and `doctor` reports it. */
|
|
30
|
+
readonly configProblem?: {
|
|
31
|
+
readonly code: "E-CONFIG-MISSING" | "E-CONFIG-LOAD" | "E-CONFIG-INVALID";
|
|
32
|
+
readonly message: string;
|
|
33
|
+
};
|
|
34
|
+
/** What `release apply` runs besides the planner (the generators of the release and the tests that pack): the real ones where it is not given. */
|
|
35
|
+
readonly releasing?: ReleasingHost;
|
|
36
|
+
};
|
|
37
|
+
/** The generators a host runs: those of the configuration, in the order it declared them. */
|
|
38
|
+
export declare function generatorsOf(host: Host): readonly Generator[];
|
|
39
|
+
/** A verb, once it is given the host it runs on. */
|
|
40
|
+
export type Make = (host: Host) => Command;
|
|
41
|
+
/** The traits of a verb as an action: its facts and its reach, from the one table. */
|
|
42
|
+
export declare function traitsOf(id: VerbId): ActionTraits;
|
|
43
|
+
/** A finding as the problem of a run: its level, its code and the fix. */
|
|
44
|
+
export declare function problemOf(f: Finding): Problem;
|
|
45
|
+
/** What a verb's body gives: the data (what `--json` carries), the text for a person, the findings, and what to run next. */
|
|
46
|
+
export type Done = {
|
|
47
|
+
readonly data: unknown;
|
|
48
|
+
readonly text: string;
|
|
49
|
+
readonly findings: readonly Finding[];
|
|
50
|
+
readonly next?: readonly string[];
|
|
51
|
+
readonly title?: string;
|
|
52
|
+
};
|
|
53
|
+
/** A run that ends well or with its findings. */
|
|
54
|
+
export declare function outcomeOfDone(d: Done): Outcome;
|
|
55
|
+
/** A run that could not be made: the checkout is not found, or the host cannot do it. */
|
|
56
|
+
export declare function outcomeOfEnvironment(message: string): Outcome;
|
|
57
|
+
/** A run that cannot be made because the repository has no usable configuration. */
|
|
58
|
+
export declare function outcomeOfConfig(p: NonNullable<Host["configProblem"]>): Outcome;
|
|
59
|
+
/** A run whose command line does not fit what the verb takes. */
|
|
60
|
+
export declare function outcomeOfUsage(message: string, code?: "E-USAGE" | "E-COMMIT-SUBJECT" | "E-COMMIT-REFS" | "E-COMMIT-SESSION" | "E-LIBRARY-NAME", fix?: string): Outcome;
|
|
61
|
+
/** What a verb is declared with. */
|
|
62
|
+
export type VerbDefinition<S extends Spec> = {
|
|
63
|
+
readonly name: string;
|
|
64
|
+
readonly id: VerbId;
|
|
65
|
+
readonly options: S & SpecCheck<S>;
|
|
66
|
+
readonly operands?: readonly Operand[];
|
|
67
|
+
readonly examples: readonly Example[];
|
|
68
|
+
readonly run: (args: Args<S>, ctx: Context, world: World, host: Host) => Promise<Outcome>;
|
|
69
|
+
/** Whether the verb is run only where the repository has a valid configuration (the default); `doctor` is not, since it is what says there is none. */
|
|
70
|
+
readonly needsConfig?: boolean;
|
|
71
|
+
};
|
|
72
|
+
/** A verb from its declaration: its summary and traits are the table's, and its body runs in the world of the host, or ends with the sentence that says the checkout was not found. */
|
|
73
|
+
export declare function defineVerb<S extends Spec>(d: VerbDefinition<S>): Make;
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Physical layer of Repoctl (commons repoctl 0006-repoctl-surfaces): what touches the world. The adapters fill the ports of the Logical layer (programs run, files read and written, the registry of npm asked, the credential read),
|
|
3
|
+
* and the program is the tree of verbs on Headless, with the tool server that serves them by audience tier. It imports Governance, Logical, Headless, the parser of the terminal, the system and the libraries of commons whose functions it
|
|
4
|
+
* calls instead of making them again.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```ts
|
|
8
|
+
* import { INERT_HOST, repoctlProgram } from "@intellectual-frontiers/repoctl/physical";
|
|
9
|
+
* repoctlProgram(INERT_HOST).children.length > 0; // true
|
|
10
|
+
* ```
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
export * from "./adapters.js";
|
|
15
|
+
export * from "./config-load.js";
|
|
16
|
+
export * from "./define.js";
|
|
17
|
+
export * from "./prove.js";
|
|
18
|
+
export * from "./prove-run.js";
|
|
19
|
+
export * from "./program.js";
|
|
20
|
+
export * from "./tests.js";
|
|
21
|
+
export * from "./verbs/check.js";
|
|
22
|
+
export * from "./verbs/docs.js";
|
|
23
|
+
export * from "./verbs/library.js";
|
|
24
|
+
export * from "./verbs/prove.js";
|
|
25
|
+
export * from "./verbs/releasing.js";
|
|
26
|
+
export * from "./verbs/sync.js";
|