docks-kit 0.25.0 → 0.27.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/AGENTS.md +12 -10
- package/README.md +40 -30
- package/cli/dist/docks-kit.js +24701 -0
- package/cli/docs/command-guards.md +8 -5
- package/cli/docs/install.md +41 -32
- package/cli/docs/omp-context.md +1 -1
- package/cli/docs/omp-models.md +1 -1
- package/cli/docs/overview.md +3 -3
- package/cli/docs/platforms.md +8 -8
- package/cli/src/agentDocs/agentFirstCheck.ts +786 -0
- package/cli/src/agentDocs/bridgeCheck.ts +226 -0
- package/cli/src/agentDocs/commands.ts +63 -0
- package/cli/src/agentDocs/prTemplate.ts +211 -0
- package/cli/src/agentDocs/services.ts +202 -0
- package/cli/src/agentDocs/shared.ts +730 -0
- package/cli/src/agentDocs/verifySkill.ts +136 -0
- package/cli/src/argv.ts +25 -1
- package/cli/src/commands/agentDocs.ts +29 -0
- package/cli/src/commands/plan.ts +29 -0
- package/cli/src/commands/skill.ts +29 -0
- package/cli/src/commands/update.ts +90 -66
- package/cli/src/engine-native/DESIGN.md +10 -9
- package/cli/src/engine-native/os/targets.ts +6 -19
- package/cli/src/engine.ts +0 -6
- package/cli/src/generated/sotPayload.ts +51 -79
- package/cli/src/kitHome.ts +7 -10
- package/cli/src/main.ts +12 -4
- package/cli/src/plan/bytes.ts +110 -0
- package/cli/src/plan/checkout.ts +379 -0
- package/cli/src/plan/commands.ts +1192 -0
- package/cli/src/plan/github.ts +816 -0
- package/cli/src/plan/records.ts +623 -0
- package/cli/src/plan/repository.ts +53 -0
- package/cli/src/plan/reviews.ts +292 -0
- package/cli/src/plan/services.ts +256 -0
- package/cli/src/plan/types.ts +164 -0
- package/cli/src/skills/commands.ts +142 -0
- package/cli/src/skills/config.json +30 -0
- package/cli/src/skills/files.ts +74 -0
- package/cli/src/skills/frontmatter.ts +148 -0
- package/cli/src/skills/guard.ts +366 -0
- package/cli/src/skills/kitGate.ts +406 -0
- package/cli/src/skills/rubric.ts +143 -0
- package/docks-kit +9 -40
- package/docks-kit.ps1 +10 -61
- package/package.json +10 -8
package/cli/src/kitHome.ts
CHANGED
|
@@ -75,22 +75,19 @@ export interface KitHomeSources {
|
|
|
75
75
|
}
|
|
76
76
|
|
|
77
77
|
/**
|
|
78
|
-
* Resolve DOCKS_KIT_HOME, then the nearest kit ancestor of the module,
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
* the installation that is executing.
|
|
78
|
+
* Resolve DOCKS_KIT_HOME, then the nearest kit ancestor of the module, then
|
|
79
|
+
* the nearest kit ancestor of the working directory, then the executable
|
|
80
|
+
* directory. The module comes first so an unrelated checkout cannot replace
|
|
81
|
+
* the installation that is executing. The executable directory is the last
|
|
82
|
+
* resort: under Bun it holds no kit, so `update` stops with the error that the
|
|
83
|
+
* home is neither a git checkout nor a global package install.
|
|
82
84
|
*/
|
|
83
85
|
export const resolveKitHome = (sources: KitHomeSources): string => {
|
|
84
86
|
if (sources.env !== undefined && sources.env !== "") {
|
|
85
87
|
return explicitKitHome(resolve(sources.env), sources.env);
|
|
86
88
|
}
|
|
87
89
|
|
|
88
|
-
return (
|
|
89
|
-
findKitHome(sources.moduleDir) ??
|
|
90
|
-
findKitHome(dirname(sources.execPath)) ??
|
|
91
|
-
findKitHome(sources.cwd) ??
|
|
92
|
-
dirname(sources.execPath)
|
|
93
|
-
);
|
|
90
|
+
return findKitHome(sources.moduleDir) ?? findKitHome(sources.cwd) ?? dirname(sources.execPath);
|
|
94
91
|
};
|
|
95
92
|
|
|
96
93
|
export const kitHome = (): string =>
|
package/cli/src/main.ts
CHANGED
|
@@ -26,11 +26,19 @@ const root = Command.make("docks-kit", {}, () =>
|
|
|
26
26
|
yield* Console.log(
|
|
27
27
|
" docks-kit tidy [--apply] [--repo <path>] [--report] remove safe agent leftovers",
|
|
28
28
|
);
|
|
29
|
+
yield* Console.log(
|
|
30
|
+
" docks-kit plan <command> [...] GitHub-issue plan records (plan-manager helper)",
|
|
31
|
+
);
|
|
32
|
+
yield* Console.log(
|
|
33
|
+
" docks-kit agent-docs <helper> <command> [...] agent-doc checks (agent-first-setup helpers)",
|
|
34
|
+
);
|
|
35
|
+
yield* Console.log(
|
|
36
|
+
" docks-kit skill guard|score [...] SKILL.md validator and rubric score (write-skill helpers)",
|
|
37
|
+
);
|
|
29
38
|
yield* Console.log("");
|
|
30
39
|
yield* Console.log(
|
|
31
40
|
"Run 'docks-kit --help' for full option listings (also: --wizard, --completions).",
|
|
32
41
|
);
|
|
33
|
-
yield* Console.log("No-Bun recovery path: use a platform release binary.");
|
|
34
42
|
}),
|
|
35
43
|
).pipe(
|
|
36
44
|
Command.withDescription(
|
|
@@ -40,11 +48,11 @@ const root = Command.make("docks-kit", {}, () =>
|
|
|
40
48
|
);
|
|
41
49
|
|
|
42
50
|
// v4's default formatter renders `name vversion`, but the `docks-kit` launcher
|
|
43
|
-
// compares `--version` against the bare `package.json` version. The
|
|
44
|
-
//
|
|
51
|
+
// compares `--version` against the bare `package.json` version. The CLI output
|
|
52
|
+
// presenter prints the result with `Console.log`, which adds the one newline.
|
|
45
53
|
const bareVersionFormatter: CliOutput.Formatter = {
|
|
46
54
|
...CliOutput.defaultFormatter(),
|
|
47
|
-
formatVersion: (_name, version) =>
|
|
55
|
+
formatVersion: (_name, version) => version,
|
|
48
56
|
};
|
|
49
57
|
|
|
50
58
|
// Harness-private raw channel:
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Raw path bytes for `docks-kit plan`. A path is held as a string with one character per byte (latin1), so a byte
|
|
3
|
+
* that is not UTF-8 stays itself. The runtime decodes its arguments and `process.cwd()` as UTF-8 and puts U+FFFD in
|
|
4
|
+
* place of each byte that is not UTF-8, which cannot be told from a literal U+FFFD. On Linux, `/proc/self/cmdline`
|
|
5
|
+
* and `/proc/self/cwd` give the bytes. macOS paths and Windows arguments are Unicode, so there the runtime strings are
|
|
6
|
+
* exact. On another system without those files, `pwd -P` gives the working folder, which it inherits; an argument
|
|
7
|
+
* with a U+FFFD has no other source of its bytes, and its use fails closed.
|
|
8
|
+
*/
|
|
9
|
+
import path from "node:path";
|
|
10
|
+
|
|
11
|
+
import { Effect } from "effect";
|
|
12
|
+
|
|
13
|
+
import { PlanFiles, PlanProcess } from "./services";
|
|
14
|
+
|
|
15
|
+
/** The bytes, or why they cannot be known. */
|
|
16
|
+
export type Recovered<A> =
|
|
17
|
+
| { readonly ok: true; readonly value: A }
|
|
18
|
+
| { readonly ok: false; readonly cause: string };
|
|
19
|
+
|
|
20
|
+
const ARGUMENT_WITHOUT_PROC = "the bytes of an argument cannot be recovered without /proc";
|
|
21
|
+
const ARGUMENT_UNMATCHED =
|
|
22
|
+
"the bytes of an argument cannot be recovered: /proc/self/cmdline does not match the arguments";
|
|
23
|
+
const WORKING_FOLDER_LOST =
|
|
24
|
+
"the bytes of the working folder cannot be recovered without /proc or pwd -P";
|
|
25
|
+
|
|
26
|
+
// Whether a path of this system is bytes that need not be UTF-8.
|
|
27
|
+
const PATHS_ARE_BYTES = process.platform !== "darwin" && process.platform !== "win32";
|
|
28
|
+
|
|
29
|
+
/** The /proc folder; `PLAN_CLI_PROC_ROOT` (a test hook) names another, such as an empty folder for a missing /proc. */
|
|
30
|
+
const procFile = (name: string): string =>
|
|
31
|
+
path.join(process.env["PLAN_CLI_PROC_ROOT"] || "/proc", "self", name);
|
|
32
|
+
|
|
33
|
+
/** A string of this process (UTF-8 text) as one character per byte. */
|
|
34
|
+
export const asBytes = (text: string): string => Buffer.from(text, "utf8").toString("latin1");
|
|
35
|
+
|
|
36
|
+
/** The text of a byte string when its bytes are UTF-8, or undefined when they are not. */
|
|
37
|
+
export const utf8Text = (bytes: string): string | undefined => {
|
|
38
|
+
const text = Buffer.from(bytes, "latin1").toString("utf8");
|
|
39
|
+
return asBytes(text) === bytes ? text : undefined;
|
|
40
|
+
};
|
|
41
|
+
|
|
42
|
+
// A run of U+FFFD, which one invalid sequence or several give, depending on the decoder.
|
|
43
|
+
const REPLACEMENTS = /\uFFFD+/g;
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* The bytes of `args`, the last words of the command line of this process, one byte string each. Each word of
|
|
47
|
+
* `/proc/self/cmdline` must decode to its argument, so a word maps to its argument and no other. Without a mapped
|
|
48
|
+
* word, the text of an argument is its bytes unless it holds a U+FFFD on a system whose paths are bytes.
|
|
49
|
+
*/
|
|
50
|
+
export const argumentBytes = Effect.fn("plan.argumentBytes")(function* (
|
|
51
|
+
args: ReadonlyArray<string>,
|
|
52
|
+
) {
|
|
53
|
+
const files = yield* PlanFiles;
|
|
54
|
+
// A /proc entry that exists but cannot be read (a sandbox can deny it) counts as no /proc.
|
|
55
|
+
const commandLine = yield* files
|
|
56
|
+
.readBytes(procFile("cmdline"))
|
|
57
|
+
.pipe(Effect.catchTag("FileError", () => Effect.undefined));
|
|
58
|
+
const lost = PATHS_ARE_BYTES && args.some((arg) => arg.includes("\uFFFD"));
|
|
59
|
+
if (commandLine === undefined) {
|
|
60
|
+
const recovered: Recovered<ReadonlyArray<string>> = lost
|
|
61
|
+
? { ok: false, cause: ARGUMENT_WITHOUT_PROC }
|
|
62
|
+
: { ok: true, value: args.map(asBytes) };
|
|
63
|
+
return recovered;
|
|
64
|
+
}
|
|
65
|
+
// Each word ends with a NUL.
|
|
66
|
+
const words = commandLine.toString("latin1").split("\0").slice(0, -1);
|
|
67
|
+
const tail = args.length === 0 ? [] : words.slice(-args.length);
|
|
68
|
+
const decoded = (word: string): string =>
|
|
69
|
+
Buffer.from(word, "latin1").toString("utf8").replace(REPLACEMENTS, "\uFFFD");
|
|
70
|
+
const matched =
|
|
71
|
+
tail.length === args.length &&
|
|
72
|
+
tail.every((word, index) => decoded(word) === args[index]?.replace(REPLACEMENTS, "\uFFFD"));
|
|
73
|
+
const recovered: Recovered<ReadonlyArray<string>> = matched
|
|
74
|
+
? { ok: true, value: tail }
|
|
75
|
+
: lost
|
|
76
|
+
? { ok: false, cause: ARGUMENT_UNMATCHED }
|
|
77
|
+
: { ok: true, value: args.map(asBytes) };
|
|
78
|
+
return recovered;
|
|
79
|
+
});
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* The bytes of the working folder of this process: from `/proc/self/cwd`, else from the runtime string when it holds
|
|
83
|
+
* no U+FFFD or the system paths are Unicode, else from the `pwd -P` utility, whose output is the physical working
|
|
84
|
+
* folder that it inherits, read as bytes, without its one trailing newline.
|
|
85
|
+
*/
|
|
86
|
+
export const workingFolderBytes = Effect.fn("plan.workingFolderBytes")(function* () {
|
|
87
|
+
const files = yield* PlanFiles;
|
|
88
|
+
const target = yield* files
|
|
89
|
+
.linkTarget(procFile("cwd"))
|
|
90
|
+
.pipe(Effect.catchTag("FileError", () => Effect.undefined));
|
|
91
|
+
if (target !== undefined) {
|
|
92
|
+
const recovered: Recovered<string> = { ok: true, value: target.toString("latin1") };
|
|
93
|
+
return recovered;
|
|
94
|
+
}
|
|
95
|
+
const cwd = process.cwd();
|
|
96
|
+
if (!PATHS_ARE_BYTES || !cwd.includes("\uFFFD")) {
|
|
97
|
+
const recovered: Recovered<string> = { ok: true, value: asBytes(cwd) };
|
|
98
|
+
return recovered;
|
|
99
|
+
}
|
|
100
|
+
const processes = yield* PlanProcess;
|
|
101
|
+
const printed = yield* processes
|
|
102
|
+
.run("pwd", ["-P"], { encoding: "latin1" })
|
|
103
|
+
.pipe(Effect.catchTag("SpawnError", () => Effect.undefined));
|
|
104
|
+
const folder =
|
|
105
|
+
printed?.error === undefined && printed?.status === 0 ? printed.stdout.replace(/\n$/, "") : "";
|
|
106
|
+
const recovered: Recovered<string> = folder.startsWith("/")
|
|
107
|
+
? { ok: true, value: folder }
|
|
108
|
+
: { ok: false, cause: WORKING_FOLDER_LOST };
|
|
109
|
+
return recovered;
|
|
110
|
+
});
|
|
@@ -0,0 +1,379 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `docks-kit plan base-blob` and `docks-kit plan checkout-state`: the former shell helpers `base-blob.sh` and
|
|
3
|
+
* `checkout-state.sh`, over git, with their output and exit codes. Paths are byte strings (`bytes.ts`): the arguments
|
|
4
|
+
* and git output keep each byte as one character, and each byte is written back as the same byte. git prints its own
|
|
5
|
+
* errors on stderr, as it did under the shell scripts.
|
|
6
|
+
*/
|
|
7
|
+
import path from "node:path";
|
|
8
|
+
|
|
9
|
+
import { Effect } from "effect";
|
|
10
|
+
|
|
11
|
+
import { argumentBytes, asBytes, utf8Text, workingFolderBytes } from "./bytes";
|
|
12
|
+
import { PlanFiles, PlanProcess, type ProcessOptions, type ProcessResult } from "./services";
|
|
13
|
+
import type { FileError, SpawnError } from "./types";
|
|
14
|
+
|
|
15
|
+
const BASE_BLOB_USAGE = "usage: docks-kit plan base-blob <commit> <path>";
|
|
16
|
+
const CHECKOUT_STATE_USAGE = "usage: docks-kit plan checkout-state <checkout>";
|
|
17
|
+
// The walk follows at most 40 links, as git and Linux do. This also ends a loop.
|
|
18
|
+
const MAX_LINKS = 40;
|
|
19
|
+
const OBJECT_ID = /^[0-9a-f]{40,64}$/;
|
|
20
|
+
|
|
21
|
+
/** `$(command)` of a shell: the output without its trailing newlines. */
|
|
22
|
+
const substituted = (result: ProcessResult): string => result.stdout.replace(/\n+$/, "");
|
|
23
|
+
|
|
24
|
+
const printError = (line: string): Effect.Effect<void> =>
|
|
25
|
+
Effect.sync(() => {
|
|
26
|
+
process.stderr.write(`${line}\n`);
|
|
27
|
+
});
|
|
28
|
+
|
|
29
|
+
/** Run git, with its stderr passed through. A git that could not start prints why. */
|
|
30
|
+
const runGit = Effect.fn("plan.runGit")(function* (
|
|
31
|
+
args: ReadonlyArray<string>,
|
|
32
|
+
options: ProcessOptions = {},
|
|
33
|
+
) {
|
|
34
|
+
const processes = yield* PlanProcess;
|
|
35
|
+
const result = yield* processes.run("git", args, {
|
|
36
|
+
...options,
|
|
37
|
+
encoding: "latin1",
|
|
38
|
+
inheritStderr: true,
|
|
39
|
+
});
|
|
40
|
+
if (result.error) yield* printError(`git: ${result.error.message}`);
|
|
41
|
+
return { result, ok: result.error === undefined && result.status === 0 };
|
|
42
|
+
});
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* The tree-ish of the root of `<commit>` (a byte string), or undefined when git fails. A commit that is UTF-8 text
|
|
46
|
+
* goes to git as the argument, as under the shell script. Other bytes cannot pass on a command line, so git reads
|
|
47
|
+
* `<commit>^{tree}` from stdin and prints the tree id. git runs in the folder `cwd`.
|
|
48
|
+
*/
|
|
49
|
+
const rootTree = Effect.fn("plan.rootTree")(function* (commit: string, cwd: string | undefined) {
|
|
50
|
+
const text = utf8Text(commit);
|
|
51
|
+
if (text !== undefined) return text;
|
|
52
|
+
const resolved = yield* runGit(["cat-file", "--batch-check=%(objectname)"], {
|
|
53
|
+
cwd,
|
|
54
|
+
input: Buffer.from(`${commit}^{tree}\n`, "latin1"),
|
|
55
|
+
});
|
|
56
|
+
if (!resolved.ok) return undefined;
|
|
57
|
+
const line = substituted(resolved.result);
|
|
58
|
+
if (OBJECT_ID.test(line)) return line;
|
|
59
|
+
// git prints `<name> missing` or `<name> ambiguous`, with the bytes of the name.
|
|
60
|
+
yield* Effect.sync(() => {
|
|
61
|
+
process.stderr.write(Buffer.from(`base-blob: ${line}\n`, "latin1"));
|
|
62
|
+
});
|
|
63
|
+
return undefined;
|
|
64
|
+
});
|
|
65
|
+
|
|
66
|
+
/** The mode and object id of a tree entry. */
|
|
67
|
+
interface TreeEntry {
|
|
68
|
+
readonly mode: string;
|
|
69
|
+
readonly oid: string;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* The entry `name` of the tree `tree` (a commit names its root tree), undefined when the tree has no such entry, or
|
|
74
|
+
* 2 when git fails. `ls-tree -z` prints each name unquoted, as its raw bytes, so the name compares byte for byte, and
|
|
75
|
+
* no path passes to git. git runs in the folder `cwd`.
|
|
76
|
+
*/
|
|
77
|
+
const treeEntry = Effect.fn("plan.treeEntry")(function* (
|
|
78
|
+
tree: string,
|
|
79
|
+
name: string,
|
|
80
|
+
cwd: string | undefined,
|
|
81
|
+
) {
|
|
82
|
+
const listed = yield* runGit(["ls-tree", "-z", "--full-tree", tree], { cwd });
|
|
83
|
+
if (!listed.ok) return 2 as const;
|
|
84
|
+
// A record is `<mode> <type> <object id><tab><name>`.
|
|
85
|
+
for (const record of listed.result.stdout.split("\0")) {
|
|
86
|
+
const tab = record.indexOf("\t");
|
|
87
|
+
if (tab < 0 || record.slice(tab + 1) !== name) continue;
|
|
88
|
+
const [mode = "", , oid = ""] = record.slice(0, tab).split(" ");
|
|
89
|
+
const entry: TreeEntry = { mode, oid };
|
|
90
|
+
return entry;
|
|
91
|
+
}
|
|
92
|
+
return undefined;
|
|
93
|
+
});
|
|
94
|
+
|
|
95
|
+
/** The blob id that `base-blob` prints, or its exit code without output: 1 absent, 2 a git failure. */
|
|
96
|
+
type BlobLookup = string | 1 | 2;
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* The walk of `base-blob`: the blob id of the file `target` in the tree of `commit`, as a checkout of `commit` would
|
|
100
|
+
* open it. Both are byte strings. git runs in the folder `cwd`, or in the working folder when `cwd` is undefined. The
|
|
101
|
+
* walk reads one path part at a time and looks it up in the listing of the tree that it has reached, by object id. A
|
|
102
|
+
* folder link and a file link resolve from the folder that holds the link, and `..` goes to the parent of the real
|
|
103
|
+
* folder that the walk has reached. Absent (1): a missing path, a folder, a submodule, a file with more path parts
|
|
104
|
+
* after it, a link with an empty, absolute, or outside target, or more than 40 links. 2: a git failure.
|
|
105
|
+
*/
|
|
106
|
+
export const resolveBaseBlob = Effect.fn("plan.resolveBaseBlob")(function* (
|
|
107
|
+
commit: string,
|
|
108
|
+
target: string,
|
|
109
|
+
cwd?: string,
|
|
110
|
+
) {
|
|
111
|
+
// The root, resolved at the first lookup, then the object id of each folder that the walk has entered; `..` drops
|
|
112
|
+
// the last one.
|
|
113
|
+
let root: string | undefined;
|
|
114
|
+
const trees: Array<string> = [];
|
|
115
|
+
let rest = target;
|
|
116
|
+
let links = 0;
|
|
117
|
+
while (rest !== "") {
|
|
118
|
+
let part: string;
|
|
119
|
+
const slash = rest.indexOf("/");
|
|
120
|
+
// A part after a slash stays, so that `file/` and a link to `dir/` keep a part.
|
|
121
|
+
if (slash >= 0) {
|
|
122
|
+
part = rest.slice(0, slash);
|
|
123
|
+
rest = rest.slice(slash + 1) || ".";
|
|
124
|
+
} else {
|
|
125
|
+
part = rest;
|
|
126
|
+
rest = "";
|
|
127
|
+
}
|
|
128
|
+
if (part === "" || part === ".") continue;
|
|
129
|
+
if (part === "..") {
|
|
130
|
+
if (trees.length === 0) return 1;
|
|
131
|
+
trees.pop();
|
|
132
|
+
continue;
|
|
133
|
+
}
|
|
134
|
+
root ??= yield* rootTree(commit, cwd);
|
|
135
|
+
if (root === undefined) return 2;
|
|
136
|
+
const entry = yield* treeEntry(trees.at(-1) ?? root, part, cwd);
|
|
137
|
+
if (entry === 2) return 2;
|
|
138
|
+
if (entry === undefined) return 1;
|
|
139
|
+
switch (entry.mode) {
|
|
140
|
+
case "040000":
|
|
141
|
+
trees.push(entry.oid);
|
|
142
|
+
break;
|
|
143
|
+
case "120000": {
|
|
144
|
+
links += 1;
|
|
145
|
+
if (links > MAX_LINKS) return 1;
|
|
146
|
+
const blob = yield* runGit(["cat-file", "blob", entry.oid], { cwd });
|
|
147
|
+
if (!blob.ok) return 2;
|
|
148
|
+
// The raw bytes of the target; its trailing newlines are part of its name.
|
|
149
|
+
const linkTarget = blob.result.stdout;
|
|
150
|
+
if (linkTarget === "" || linkTarget.startsWith("/")) return 1;
|
|
151
|
+
rest = rest ? `${linkTarget}/${rest}` : linkTarget;
|
|
152
|
+
break;
|
|
153
|
+
}
|
|
154
|
+
case "100644":
|
|
155
|
+
case "100755":
|
|
156
|
+
if (rest) return 1;
|
|
157
|
+
return entry.oid;
|
|
158
|
+
default:
|
|
159
|
+
return 1;
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
return 1;
|
|
163
|
+
});
|
|
164
|
+
|
|
165
|
+
/**
|
|
166
|
+
* `base-blob <commit> <path>`: print the blob id of the file `<path>` in the tree of `<commit>` (`resolveBaseBlob`) and
|
|
167
|
+
* return 0. The arguments are read as bytes. Exit 1: absent. Exit 2: a git failure, wrong arguments, or an argument
|
|
168
|
+
* whose bytes cannot be recovered (a U+FFFD without /proc, see `bytes.ts`).
|
|
169
|
+
*/
|
|
170
|
+
export const baseBlob = Effect.fn("plan.baseBlob")(function* (args: ReadonlyArray<string>) {
|
|
171
|
+
if (args.length !== 2 || !args[0]) {
|
|
172
|
+
yield* printError(BASE_BLOB_USAGE);
|
|
173
|
+
return 2;
|
|
174
|
+
}
|
|
175
|
+
const bytes = yield* argumentBytes(args);
|
|
176
|
+
if (!bytes.ok) {
|
|
177
|
+
yield* printError(`base-blob: ${bytes.cause}`);
|
|
178
|
+
return 2;
|
|
179
|
+
}
|
|
180
|
+
const [commit = "", target = ""] = bytes.value;
|
|
181
|
+
const blob: BlobLookup = yield* resolveBaseBlob(commit, target);
|
|
182
|
+
if (blob === 1 || blob === 2) return blob;
|
|
183
|
+
yield* Effect.sync(() => {
|
|
184
|
+
process.stdout.write(`${blob}\n`);
|
|
185
|
+
});
|
|
186
|
+
return 0;
|
|
187
|
+
});
|
|
188
|
+
|
|
189
|
+
/**
|
|
190
|
+
* `resolveBaseBlob` in this process, for a synchronous caller outside the CLI: the review-benchmark scripts read many
|
|
191
|
+
* instruction files, and one CLI process per file costs a Bun start each. `commit` and `target` are UTF-8 text; git
|
|
192
|
+
* runs in the repository folder `cwd` and prints its errors on stderr. A git that could not start is a failure (2), as
|
|
193
|
+
* under `docks-kit plan base-blob`.
|
|
194
|
+
*/
|
|
195
|
+
export const baseBlobSync = (cwd: string, commit: string, target: string): BlobLookup =>
|
|
196
|
+
Effect.runSync(
|
|
197
|
+
resolveBaseBlob(asBytes(commit), asBytes(target), cwd).pipe(
|
|
198
|
+
Effect.catchTag("SpawnError", (error) =>
|
|
199
|
+
printError(error.message).pipe(Effect.as(2 as const)),
|
|
200
|
+
),
|
|
201
|
+
Effect.provide(PlanProcess.layer),
|
|
202
|
+
),
|
|
203
|
+
);
|
|
204
|
+
|
|
205
|
+
/** The sorted listing lines of a checkout, or the exit code of a failed listing. */
|
|
206
|
+
type Listing = ReadonlyArray<string> | 1 | 2;
|
|
207
|
+
|
|
208
|
+
/** The links of one checkout-state run: their private scratch folder, made at the first link, and their count. */
|
|
209
|
+
interface GitFolders {
|
|
210
|
+
folder: string | undefined;
|
|
211
|
+
links: number;
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
/**
|
|
215
|
+
* A path that git takes on its command line for the absolute folder `bytes`: the folder itself when its bytes are
|
|
216
|
+
* UTF-8, otherwise a link with an ASCII name, in the scratch folder of the run, whose target holds the bytes. git
|
|
217
|
+
* runs in the real folder, so a path that it prints keeps its bytes.
|
|
218
|
+
*/
|
|
219
|
+
const gitFolder = Effect.fn("plan.gitFolder")(function* (folders: GitFolders, bytes: string) {
|
|
220
|
+
const text = utf8Text(bytes);
|
|
221
|
+
if (text !== undefined) return text;
|
|
222
|
+
const files = yield* PlanFiles;
|
|
223
|
+
const folder = folders.folder ?? (yield* files.scratchFolder("plan-git-folders"));
|
|
224
|
+
folders.folder = folder;
|
|
225
|
+
const link = path.join(folder, String(folders.links));
|
|
226
|
+
folders.links += 1;
|
|
227
|
+
yield* files.symlink(Buffer.from(bytes, "latin1"), link);
|
|
228
|
+
return link;
|
|
229
|
+
});
|
|
230
|
+
|
|
231
|
+
/** `"<path>"` as `git hash-object --stdin-paths` reads a C-quoted path, so a quote, backslash, or CR keeps its byte. */
|
|
232
|
+
const quotedPath = (file: string): string =>
|
|
233
|
+
`"${file.replace(/[\\"]/g, "\\$&").replace(/\r/g, "\\r")}"`;
|
|
234
|
+
|
|
235
|
+
/** The listing of the checkout that holds the folder `checkout`, a path that git takes (see `gitFolder`). */
|
|
236
|
+
const checkoutListing: (
|
|
237
|
+
checkout: string,
|
|
238
|
+
folders: GitFolders,
|
|
239
|
+
) => Effect.Effect<Listing, FileError | SpawnError, PlanProcess | PlanFiles> = Effect.fn(
|
|
240
|
+
"plan.checkoutListing",
|
|
241
|
+
)(function* (checkout: string, folders: GitFolders) {
|
|
242
|
+
const files = yield* PlanFiles;
|
|
243
|
+
const env = { ...process.env, LC_ALL: "C" };
|
|
244
|
+
const top = yield* runGit(["-C", checkout, "rev-parse", "--show-toplevel"], { env });
|
|
245
|
+
if (!top.ok) return 2;
|
|
246
|
+
const topPath = substituted(top.result);
|
|
247
|
+
const topFolder = yield* gitFolder(folders, topPath);
|
|
248
|
+
const listed = yield* runGit(
|
|
249
|
+
["-C", topFolder, "ls-files", "-z", "--cached", "--others", "--exclude-standard"],
|
|
250
|
+
{ env },
|
|
251
|
+
);
|
|
252
|
+
if (!listed.ok) return 2;
|
|
253
|
+
if (/[\t\n]/.test(listed.result.stdout)) {
|
|
254
|
+
yield* printError("checkout-state: a path holds a tab or a newline");
|
|
255
|
+
return 1;
|
|
256
|
+
}
|
|
257
|
+
// An untracked repository is listed as `<path>/`. An unmerged path is listed once per stage; one line stays.
|
|
258
|
+
const names = listed.result.stdout.split("\0");
|
|
259
|
+
names.pop();
|
|
260
|
+
const paths = [...new Set(names.map((name) => name.replace(/\/$/, "")))].sort();
|
|
261
|
+
const lines: Array<string> = [];
|
|
262
|
+
const regular: Array<string> = [];
|
|
263
|
+
const executable: Array<string> = [];
|
|
264
|
+
for (const name of paths) {
|
|
265
|
+
const file = `${topPath}/${name}`;
|
|
266
|
+
const entry = yield* files.entry(Buffer.from(file, "latin1"));
|
|
267
|
+
switch (entry.kind) {
|
|
268
|
+
case "link":
|
|
269
|
+
if (entry.target.includes("\n")) {
|
|
270
|
+
yield* printError("checkout-state: a link target holds a newline");
|
|
271
|
+
return 1;
|
|
272
|
+
}
|
|
273
|
+
lines.push(`${name}\tlink\t${entry.target}`);
|
|
274
|
+
break;
|
|
275
|
+
case "file":
|
|
276
|
+
regular.push(name);
|
|
277
|
+
executable.push(entry.executable ? "x" : "");
|
|
278
|
+
break;
|
|
279
|
+
case "directory": {
|
|
280
|
+
const folder = yield* gitFolder(folders, file);
|
|
281
|
+
// A folder that is not a checkout gives the toplevel of the outer checkout.
|
|
282
|
+
const sub = yield* runGit(["-C", folder, "rev-parse", "--show-toplevel"], { env });
|
|
283
|
+
if (!sub.ok) return 2;
|
|
284
|
+
if (substituted(sub.result) !== file) {
|
|
285
|
+
lines.push(`${name}\tspecial`);
|
|
286
|
+
break;
|
|
287
|
+
}
|
|
288
|
+
const head = yield* runGit(["-C", folder, "rev-parse", "HEAD"], { env });
|
|
289
|
+
if (!head.ok) return 2;
|
|
290
|
+
lines.push(`${name}\tsubmodule\t${substituted(head.result)}`);
|
|
291
|
+
// The status of the submodule listing is the status of this listing.
|
|
292
|
+
const nested = yield* checkoutListing(folder, folders);
|
|
293
|
+
if (nested === 1 || nested === 2) return nested;
|
|
294
|
+
for (const line of nested) lines.push(`${name}/${line}`);
|
|
295
|
+
break;
|
|
296
|
+
}
|
|
297
|
+
case "special":
|
|
298
|
+
lines.push(`${name}\tspecial`);
|
|
299
|
+
break;
|
|
300
|
+
case "missing":
|
|
301
|
+
lines.push(`${name}\tmissing`);
|
|
302
|
+
break;
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
if (regular.length > 0) {
|
|
306
|
+
// One hash-object process reads all regular files, with the raw bytes on disk and no filter.
|
|
307
|
+
const input = Buffer.from(regular.map((name) => `${quotedPath(name)}\n`).join(""), "latin1");
|
|
308
|
+
const hashed = yield* runGit(
|
|
309
|
+
["-C", topFolder, "hash-object", "--no-filters", "--stdin-paths"],
|
|
310
|
+
{ env, input },
|
|
311
|
+
);
|
|
312
|
+
if (!hashed.ok) return 2;
|
|
313
|
+
const blobs = hashed.result.stdout.split("\n");
|
|
314
|
+
regular.forEach((name, index) =>
|
|
315
|
+
lines.push(`${name}\t${blobs[index] ?? ""}\t${executable[index]}`.replace(/\t$/, "")),
|
|
316
|
+
);
|
|
317
|
+
}
|
|
318
|
+
// Each character is one byte, so the default order is the byte order of `LC_ALL=C sort`.
|
|
319
|
+
return lines.sort();
|
|
320
|
+
});
|
|
321
|
+
|
|
322
|
+
/** The listing of the checkout that holds the argument `checkout`; the links of the run go away at its end. */
|
|
323
|
+
const listCheckout = Effect.fn("plan.listCheckout")(function* (checkout: string) {
|
|
324
|
+
const bytes = yield* argumentBytes([checkout]);
|
|
325
|
+
if (!bytes.ok) {
|
|
326
|
+
yield* printError(`checkout-state: ${bytes.cause}`);
|
|
327
|
+
return 1 as const;
|
|
328
|
+
}
|
|
329
|
+
let folderBytes = bytes.value[0] ?? "";
|
|
330
|
+
// A relative path that is UTF-8 goes to git as it is, and git resolves it from the working folder that it inherits;
|
|
331
|
+
// other bytes reach git through a link, whose target must be absolute.
|
|
332
|
+
if (utf8Text(folderBytes) === undefined && !path.isAbsolute(folderBytes)) {
|
|
333
|
+
const working = yield* workingFolderBytes();
|
|
334
|
+
if (!working.ok) {
|
|
335
|
+
yield* printError(`checkout-state: ${working.cause}`);
|
|
336
|
+
return 1 as const;
|
|
337
|
+
}
|
|
338
|
+
folderBytes = `${working.value}/${folderBytes}`;
|
|
339
|
+
}
|
|
340
|
+
return yield* Effect.acquireUseRelease(
|
|
341
|
+
Effect.sync((): GitFolders => ({ folder: undefined, links: 0 })),
|
|
342
|
+
(folders) =>
|
|
343
|
+
gitFolder(folders, folderBytes).pipe(
|
|
344
|
+
Effect.flatMap((folder) => checkoutListing(folder, folders)),
|
|
345
|
+
),
|
|
346
|
+
({ folder }) =>
|
|
347
|
+
folder === undefined ? Effect.void : PlanFiles.use((files) => files.removeFolder(folder)),
|
|
348
|
+
);
|
|
349
|
+
});
|
|
350
|
+
|
|
351
|
+
/**
|
|
352
|
+
* `checkout-state <checkout>`: print the state on disk of each cached or untracked, not ignored path of the checkout
|
|
353
|
+
* that holds `<checkout>`, one sorted line per path, and return 0. Lines: `<path>\t<blob id>[\tx]` for a regular file
|
|
354
|
+
* (raw bytes, `x` when executable), `<path>\tlink\t<target>`, `<path>\tsubmodule\t<head>` followed by the lines of the
|
|
355
|
+
* submodule under `<path>/`, `<path>\tmissing`, and `<path>\tspecial`. Paths keep their bytes, also when they are not
|
|
356
|
+
* UTF-8. Exit 1: a path with a tab or a newline, a link target with a newline, or a `<checkout>` whose bytes cannot
|
|
357
|
+
* be recovered (a U+FFFD without /proc, see `bytes.ts`). Exit 2: a failed command or wrong arguments. A failure
|
|
358
|
+
* prints nothing on stdout.
|
|
359
|
+
*/
|
|
360
|
+
export const checkoutState = Effect.fn("plan.checkoutState")(function* (
|
|
361
|
+
args: ReadonlyArray<string>,
|
|
362
|
+
) {
|
|
363
|
+
if (args.length !== 1 || !args[0]) {
|
|
364
|
+
yield* printError(CHECKOUT_STATE_USAGE);
|
|
365
|
+
return 2;
|
|
366
|
+
}
|
|
367
|
+
const listing = yield* listCheckout(args[0]).pipe(
|
|
368
|
+
Effect.catchTags({
|
|
369
|
+
FileError: (error) => printError(error.message).pipe(Effect.as(2 as const)),
|
|
370
|
+
SpawnError: (error) => printError(error.message).pipe(Effect.as(2 as const)),
|
|
371
|
+
}),
|
|
372
|
+
);
|
|
373
|
+
if (listing === 1 || listing === 2) return listing;
|
|
374
|
+
const output = Buffer.from(listing.map((line) => `${line}\n`).join(""), "latin1");
|
|
375
|
+
yield* Effect.sync(() => {
|
|
376
|
+
process.stdout.write(output);
|
|
377
|
+
});
|
|
378
|
+
return 0;
|
|
379
|
+
});
|