docks-kit 0.24.0 → 0.26.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 +21 -136
- package/README.md +54 -9
- package/cli/dist/docks-kit.js +24688 -0
- package/cli/docs/command-guards.md +1 -1
- package/cli/docs/install.md +30 -9
- package/cli/docs/omp-context.md +1 -1
- package/cli/docs/omp-models.md +5 -4
- package/cli/docs/sync-layers.md +46 -75
- package/cli/docs/toolchain.md +4 -5
- 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 -31
- package/cli/src/engine-native/DESIGN.md +5 -6
- package/cli/src/engine-native/engineCtx.ts +0 -3
- package/cli/src/engine-native/failures.ts +2 -2
- package/cli/src/engine-native/ompChild.ts +1 -1
- package/cli/src/engine-native/ompKitPlugin.ts +7 -16
- package/cli/src/engine-native/ompPlugins.ts +205 -221
- package/cli/src/engine-native/ompSync.ts +5 -14
- package/cli/src/generated/sotPayload.ts +308 -12
- package/cli/src/main.ts +12 -3
- package/cli/src/plan/bytes.ts +110 -0
- package/cli/src/plan/checkout.ts +341 -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/cli/tsconfig.json +1 -0
- package/package.json +7 -4
- package/cli/src/engine-native/ompMarketplace.ts +0 -140
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The services of `docks-kit agent-docs`: git and files. Each file method mirrors one `fs` call of the agent-doc
|
|
3
|
+
* helper scripts with the same symlink handling; a call that the scripts treated as a test (`test -f`, `test -L`)
|
|
4
|
+
* never fails. The command entry provides `AgentDocsServicesLive`.
|
|
5
|
+
*/
|
|
6
|
+
import { spawnSync } from "node:child_process";
|
|
7
|
+
import fs from "node:fs";
|
|
8
|
+
|
|
9
|
+
import { Context, Effect, Layer, Predicate } from "effect";
|
|
10
|
+
|
|
11
|
+
import { FileError, SpawnError } from "../plan/types";
|
|
12
|
+
|
|
13
|
+
// Room for the listing of a very large repository; the default of 1 MiB would cut it off.
|
|
14
|
+
const OUTPUT_BUFFER = 256 * 1024 * 1024;
|
|
15
|
+
|
|
16
|
+
/** The end of one git run, as `spawnSync` reports it. */
|
|
17
|
+
export interface GitResult {
|
|
18
|
+
readonly status: number | null;
|
|
19
|
+
readonly signal: string | null;
|
|
20
|
+
readonly stdout: string;
|
|
21
|
+
readonly stderr: string;
|
|
22
|
+
/** Set when git could not start, or its output passed the limit. */
|
|
23
|
+
readonly error: { readonly message: string } | undefined;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** What `stat` sees at a path, through symlinks. */
|
|
27
|
+
export type StatKind = "file" | "directory" | "other";
|
|
28
|
+
|
|
29
|
+
/** What a folder listing sees for one entry, without following a symlink. */
|
|
30
|
+
export type EntryKind = "file" | "directory" | "symlink" | "other";
|
|
31
|
+
|
|
32
|
+
export interface FolderEntry {
|
|
33
|
+
readonly name: string;
|
|
34
|
+
readonly kind: EntryKind;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
const errorCode = (error: unknown): string | undefined => {
|
|
38
|
+
const code = Predicate.hasProperty(error, "code") ? error.code : undefined;
|
|
39
|
+
return Predicate.isString(code) ? code : undefined;
|
|
40
|
+
};
|
|
41
|
+
|
|
42
|
+
const errorMessage = (error: unknown): string =>
|
|
43
|
+
error instanceof Error ? error.message : String(error);
|
|
44
|
+
|
|
45
|
+
/** The text that the scripts print for a failed call: `error.code ?? error.message`. */
|
|
46
|
+
export const errorDetail = (error: FileError): string => error.code ?? error.message;
|
|
47
|
+
|
|
48
|
+
const fileOperation = <A>(operation: () => A): Effect.Effect<A, FileError> =>
|
|
49
|
+
Effect.try({
|
|
50
|
+
try: operation,
|
|
51
|
+
catch: (error) => new FileError({ message: errorMessage(error), code: errorCode(error) }),
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
/** True when the call does not throw: `test -e`, `test -L`, and the like. */
|
|
55
|
+
const succeeds = (operation: () => unknown): boolean => {
|
|
56
|
+
try {
|
|
57
|
+
operation();
|
|
58
|
+
return true;
|
|
59
|
+
} catch {
|
|
60
|
+
return false;
|
|
61
|
+
}
|
|
62
|
+
};
|
|
63
|
+
|
|
64
|
+
function statKind(file: string): StatKind | undefined {
|
|
65
|
+
let stats: fs.Stats;
|
|
66
|
+
try {
|
|
67
|
+
stats = fs.statSync(file);
|
|
68
|
+
} catch {
|
|
69
|
+
return undefined;
|
|
70
|
+
}
|
|
71
|
+
if (stats.isFile()) return "file";
|
|
72
|
+
return stats.isDirectory() ? "directory" : "other";
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
function entryKind(entry: fs.Dirent): EntryKind {
|
|
76
|
+
if (entry.isSymbolicLink()) return "symlink";
|
|
77
|
+
if (entry.isFile()) return "file";
|
|
78
|
+
return entry.isDirectory() ? "directory" : "other";
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
function runGit(args: ReadonlyArray<string>, cwd: string | undefined): GitResult {
|
|
82
|
+
const result = spawnSync("git", [...args], { cwd, encoding: "utf8", maxBuffer: OUTPUT_BUFFER });
|
|
83
|
+
return {
|
|
84
|
+
status: result.status,
|
|
85
|
+
signal: result.signal,
|
|
86
|
+
stdout: result.stdout ?? "",
|
|
87
|
+
stderr: result.stderr ?? "",
|
|
88
|
+
error: result.error === undefined ? undefined : { message: result.error.message },
|
|
89
|
+
};
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** Runs git with an argv and no shell, and waits for it; the scripts' `spawnSync('git', ...)`. */
|
|
93
|
+
export class AgentDocsGit extends Context.Service<
|
|
94
|
+
AgentDocsGit,
|
|
95
|
+
{
|
|
96
|
+
/**
|
|
97
|
+
* Run git in `cwd`, or in the working folder; the output is UTF-8 text. Fails only when the runtime refuses the
|
|
98
|
+
* arguments before git starts.
|
|
99
|
+
*/
|
|
100
|
+
readonly run: (
|
|
101
|
+
args: ReadonlyArray<string>,
|
|
102
|
+
cwd?: string,
|
|
103
|
+
) => Effect.Effect<GitResult, SpawnError>;
|
|
104
|
+
}
|
|
105
|
+
>()("docks-kit/agentDocs/AgentDocsGit") {
|
|
106
|
+
static readonly layer = Layer.succeed(
|
|
107
|
+
AgentDocsGit,
|
|
108
|
+
AgentDocsGit.of({
|
|
109
|
+
run: (args, cwd) =>
|
|
110
|
+
Effect.try({
|
|
111
|
+
try: () => runGit(args, cwd),
|
|
112
|
+
catch: (error) => new SpawnError({ message: errorMessage(error) }),
|
|
113
|
+
}),
|
|
114
|
+
}),
|
|
115
|
+
);
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/** File access of the agent-doc checks. A failure carries the Node error message and code. */
|
|
119
|
+
export class AgentDocsFiles extends Context.Service<
|
|
120
|
+
AgentDocsFiles,
|
|
121
|
+
{
|
|
122
|
+
/** `fs.statSync`, which follows symlinks; undefined when the call fails. */
|
|
123
|
+
readonly stat: (file: string) => Effect.Effect<StatKind | undefined>;
|
|
124
|
+
/** `test -L`: a failed lstat, for example below a file, means no symlink. */
|
|
125
|
+
readonly isSymlink: (file: string) => Effect.Effect<boolean>;
|
|
126
|
+
/** True when an entry is at `file`, a dangling symlink included (`test -e || test -L`). */
|
|
127
|
+
readonly entryExists: (file: string) => Effect.Effect<boolean>;
|
|
128
|
+
/** `fs.existsSync`, which follows symlinks. */
|
|
129
|
+
readonly exists: (file: string) => Effect.Effect<boolean>;
|
|
130
|
+
/** The entries of a folder, through a symlink too, in the order of the system. */
|
|
131
|
+
readonly readFolder: (folder: string) => Effect.Effect<ReadonlyArray<FolderEntry>, FileError>;
|
|
132
|
+
/** The text of a file; `latin1` gives one character per byte. */
|
|
133
|
+
readonly readFile: (
|
|
134
|
+
file: string,
|
|
135
|
+
encoding: "utf8" | "latin1",
|
|
136
|
+
) => Effect.Effect<string, FileError>;
|
|
137
|
+
readonly readLink: (file: string) => Effect.Effect<string, FileError>;
|
|
138
|
+
/** `fs.realpathSync`. */
|
|
139
|
+
readonly realPath: (file: string) => Effect.Effect<string, FileError>;
|
|
140
|
+
/** `fs.realpathSync.native`, which resolves each part as the kernel does. */
|
|
141
|
+
readonly realPathNative: (file: string) => Effect.Effect<string, FileError>;
|
|
142
|
+
/** Fails unless `cd` may enter the folder (search permission). */
|
|
143
|
+
readonly canSearch: (folder: string) => Effect.Effect<void, FileError>;
|
|
144
|
+
/** The physical working folder, as `pwd -P` prints it. */
|
|
145
|
+
readonly workingFolder: Effect.Effect<string>;
|
|
146
|
+
readonly changeFolder: (folder: string) => Effect.Effect<void, FileError>;
|
|
147
|
+
/** The `HOME` variable of the environment. */
|
|
148
|
+
readonly home: Effect.Effect<string | undefined>;
|
|
149
|
+
}
|
|
150
|
+
>()("docks-kit/agentDocs/AgentDocsFiles") {
|
|
151
|
+
static readonly layer = Layer.effect(
|
|
152
|
+
AgentDocsFiles,
|
|
153
|
+
Effect.sync(() =>
|
|
154
|
+
AgentDocsFiles.of({
|
|
155
|
+
stat: (file) => Effect.sync(() => statKind(file)),
|
|
156
|
+
isSymlink: (file) =>
|
|
157
|
+
Effect.sync(() => {
|
|
158
|
+
try {
|
|
159
|
+
return fs.lstatSync(file).isSymbolicLink();
|
|
160
|
+
} catch {
|
|
161
|
+
return false;
|
|
162
|
+
}
|
|
163
|
+
}),
|
|
164
|
+
entryExists: (file) => Effect.sync(() => succeeds(() => fs.lstatSync(file))),
|
|
165
|
+
exists: (file) => Effect.sync(() => fs.existsSync(file)),
|
|
166
|
+
readFolder: (folder) =>
|
|
167
|
+
fileOperation(() =>
|
|
168
|
+
fs
|
|
169
|
+
.readdirSync(folder, { withFileTypes: true })
|
|
170
|
+
.map((entry): FolderEntry => ({ name: entry.name, kind: entryKind(entry) })),
|
|
171
|
+
),
|
|
172
|
+
// Node's readFileSync with an encoding decodes the bytes as Buffer#toString does.
|
|
173
|
+
readFile: (file, encoding) => fileOperation(() => fs.readFileSync(file).toString(encoding)),
|
|
174
|
+
readLink: (file) => fileOperation(() => fs.readlinkSync(file)),
|
|
175
|
+
realPath: (file) => fileOperation(() => fs.realpathSync(file)),
|
|
176
|
+
realPathNative: (file) => fileOperation(() => fs.realpathSync.native(file)),
|
|
177
|
+
canSearch: (folder) => fileOperation(() => fs.accessSync(folder, fs.constants.X_OK)),
|
|
178
|
+
workingFolder: Effect.sync(() => process.cwd()),
|
|
179
|
+
changeFolder: (folder) => fileOperation(() => process.chdir(folder)),
|
|
180
|
+
home: Effect.sync(() => process.env["HOME"]),
|
|
181
|
+
}),
|
|
182
|
+
),
|
|
183
|
+
);
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
export const AgentDocsServicesLive = Layer.mergeAll(AgentDocsGit.layer, AgentDocsFiles.layer);
|
|
187
|
+
|
|
188
|
+
/** Write text to stdout as is. */
|
|
189
|
+
export const writeStdout = (text: string): Effect.Effect<void> =>
|
|
190
|
+
Effect.sync(() => {
|
|
191
|
+
process.stdout.write(text);
|
|
192
|
+
});
|
|
193
|
+
|
|
194
|
+
/** Write text to stderr as is. */
|
|
195
|
+
export const writeStderr = (text: string): Effect.Effect<void> =>
|
|
196
|
+
Effect.sync(() => {
|
|
197
|
+
process.stderr.write(text);
|
|
198
|
+
});
|
|
199
|
+
|
|
200
|
+
/** Print lines on stdout, each with its newline, or nothing for no lines. */
|
|
201
|
+
export const printLines = (lines: ReadonlyArray<string>): Effect.Effect<void> =>
|
|
202
|
+
lines.length > 0 ? writeStdout(`${lines.join("\n")}\n`) : Effect.void;
|