docks-kit 0.22.12 → 0.22.20
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 +95 -81
- package/README.md +7 -7
- package/cli/docs/command-guards.md +7 -3
- package/cli/docs/flags.md +59 -9
- package/cli/docs/install.md +2 -2
- package/cli/docs/omp-context.md +14 -8
- package/cli/docs/omp-models.md +1 -1
- package/cli/docs/overview.md +1 -1
- package/cli/docs/platforms.md +4 -2
- package/cli/docs/plugins.md +8 -5
- package/cli/docs/sync-layers.md +29 -15
- package/cli/docs/toolchain.md +24 -14
- package/cli/src/argv.ts +7 -4
- package/cli/src/argvValidate.ts +2 -16
- package/cli/src/commands/docs.ts +1 -1
- package/cli/src/commands/omp.ts +56 -15
- package/cli/src/commands/sync.ts +6 -6
- package/cli/src/commands/tidy.ts +83 -26
- package/cli/src/engine-native/DESIGN.md +93 -56
- package/cli/src/engine-native/atomicWrite.ts +168 -8
- package/cli/src/engine-native/codexConfig.ts +2 -6
- package/cli/src/engine-native/codexPlugins.ts +1 -1
- package/cli/src/engine-native/codexSync.ts +137 -26
- package/cli/src/engine-native/codexToml.ts +4 -86
- package/cli/src/engine-native/deps.ts +51 -51
- package/cli/src/engine-native/exec.ts +3 -0
- package/cli/src/engine-native/index.ts +1 -1
- package/cli/src/engine-native/kitLock.ts +121 -0
- package/cli/src/engine-native/modes.ts +49 -31
- package/cli/src/engine-native/ompChild.ts +26 -0
- package/cli/src/engine-native/ompFastMode.ts +14 -7
- package/cli/src/engine-native/ompFileDeploy.ts +12 -6
- package/cli/src/engine-native/ompMarketplace.ts +25 -18
- package/cli/src/engine-native/ompPlugins.ts +39 -18
- package/cli/src/engine-native/ompRemovals.ts +51 -23
- package/cli/src/engine-native/ompSync.ts +78 -38
- package/cli/src/engine-native/os/targets.ts +16 -4
- package/cli/src/engine-native/os/types.ts +1 -1
- package/cli/src/engine-native/parseArgs.ts +27 -17
- package/cli/src/engine-native/processes.ts +16 -0
- package/cli/src/engine-native/scratch.ts +18 -0
- package/cli/src/engine-native/skillsInstall.ts +27 -2
- package/cli/src/engine-native/skillsPrune.ts +51 -49
- package/cli/src/engine-native/skillsRecords.ts +138 -0
- package/cli/src/engine-native/skillsSync.ts +16 -13
- package/cli/src/engine-native/syncDispatch.ts +186 -4
- package/cli/src/engine-native/tidy.ts +102 -119
- package/cli/src/engine-native/tomlLines.ts +92 -0
- package/cli/src/generated/sotPayload.ts +5 -5
- package/cli/src/main.ts +5 -30
- package/cli/src/manifests.ts +24 -4
- package/package.json +2 -2
- package/cli/src/engine-native/tidyLock.ts +0 -163
package/cli/src/main.ts
CHANGED
|
@@ -3,21 +3,8 @@ import { Command, CliOutput } from "effect/cli";
|
|
|
3
3
|
import { BunRuntime, BunServices } from "@effect/platform-bun";
|
|
4
4
|
import { Console, Effect, Layer } from "effect";
|
|
5
5
|
import { EngineServicesLive } from "./services";
|
|
6
|
-
import { docsCommand } from "./commands/docs";
|
|
7
|
-
import { harnessesCommand } from "./commands/harnesses";
|
|
8
|
-
import { modelCommand } from "./commands/model";
|
|
9
|
-
import { modelsCommand } from "./commands/models";
|
|
10
|
-
import { ompCommand } from "./commands/omp";
|
|
11
|
-
import { pluginsCommand } from "./commands/plugins";
|
|
12
|
-
import { skillsCommand } from "./commands/skills";
|
|
13
|
-
import { scratchCommand } from "./commands/scratch";
|
|
14
|
-
import { statusCommand } from "./commands/status";
|
|
15
|
-
import { syncCommand } from "./commands/sync";
|
|
16
|
-
import { toolchainCommand } from "./commands/toolchain";
|
|
17
|
-
import { tidyCommand } from "./commands/tidy";
|
|
18
|
-
import { updateCommand } from "./commands/update";
|
|
19
6
|
import { GENERATED_PACKAGE_VERSION } from "./generated/sotPayload";
|
|
20
|
-
import { prepareArgv } from "./argv";
|
|
7
|
+
import { COMMANDS, prepareArgv } from "./argv";
|
|
21
8
|
import { runEngineNative } from "./engine-native";
|
|
22
9
|
|
|
23
10
|
const root = Command.make("docks-kit", {}, () =>
|
|
@@ -46,7 +33,9 @@ const root = Command.make("docks-kit", {}, () =>
|
|
|
46
33
|
yield* Console.log(
|
|
47
34
|
" docks-kit scratch new|remove agent temporary files and directories",
|
|
48
35
|
);
|
|
49
|
-
yield* Console.log(
|
|
36
|
+
yield* Console.log(
|
|
37
|
+
" docks-kit tidy [--apply] [--repo <path>] [--report] remove safe agent leftovers",
|
|
38
|
+
);
|
|
50
39
|
yield* Console.log("");
|
|
51
40
|
yield* Console.log(
|
|
52
41
|
"Run 'docks-kit --help' for full option listings (also: --wizard, --completions).",
|
|
@@ -57,21 +46,7 @@ const root = Command.make("docks-kit", {}, () =>
|
|
|
57
46
|
Command.withDescription(
|
|
58
47
|
"Portable AI coding agent config kit — SoT sync engine + helpers for Claude Code, Codex, and universal agent skills.",
|
|
59
48
|
),
|
|
60
|
-
Command.withSubcommands(
|
|
61
|
-
syncCommand,
|
|
62
|
-
harnessesCommand,
|
|
63
|
-
updateCommand,
|
|
64
|
-
modelCommand,
|
|
65
|
-
modelsCommand,
|
|
66
|
-
toolchainCommand,
|
|
67
|
-
statusCommand,
|
|
68
|
-
pluginsCommand,
|
|
69
|
-
skillsCommand,
|
|
70
|
-
docsCommand,
|
|
71
|
-
ompCommand,
|
|
72
|
-
scratchCommand,
|
|
73
|
-
tidyCommand,
|
|
74
|
-
]),
|
|
49
|
+
Command.withSubcommands(COMMANDS),
|
|
75
50
|
);
|
|
76
51
|
|
|
77
52
|
// v4's default formatter renders `name vversion`, but the `docks-kit` launcher
|
package/cli/src/manifests.ts
CHANGED
|
@@ -7,6 +7,11 @@ import { isObject, readJsonFile } from "./engine-native/jq";
|
|
|
7
7
|
import type { JsonObject } from "./engine-native/sharedTypes";
|
|
8
8
|
import { skillBase } from "./engine-native/skillsManifest";
|
|
9
9
|
import { COPY_MARKER } from "./engine-native/skillsSync";
|
|
10
|
+
import {
|
|
11
|
+
isTomlHeaderLine,
|
|
12
|
+
keyValueSeparator,
|
|
13
|
+
tomlContinuationLines,
|
|
14
|
+
} from "./engine-native/tomlLines";
|
|
10
15
|
import { payloadText } from "./payload";
|
|
11
16
|
|
|
12
17
|
export type Tool = "claude" | "codex";
|
|
@@ -22,11 +27,26 @@ export const deployedClaudeSettings = (): any | undefined => {
|
|
|
22
27
|
return existsSync(p) ? readJson(p) : undefined;
|
|
23
28
|
};
|
|
24
29
|
|
|
30
|
+
/** The name of a bare, `"…"`, or `'…'` key; undefined for a dotted or escaped key. */
|
|
31
|
+
function tomlKeyName(keyText: string): string | undefined {
|
|
32
|
+
const key = keyText.trim().match(/^(?:([A-Za-z0-9_-]+)|"([^"\\]*)"|'([^']*)')$/);
|
|
33
|
+
return key?.[1] ?? key?.[2] ?? key?.[3];
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* The string value of a top-level key. Lines that continue a multi-line value
|
|
38
|
+
* are skipped, and the scan stops at the first table header.
|
|
39
|
+
*/
|
|
25
40
|
export function topLevelTomlString(text: string, setting: string): string | undefined {
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
if (
|
|
41
|
+
const lines = text.split(/\r?\n/);
|
|
42
|
+
const continuation = tomlContinuationLines(lines);
|
|
43
|
+
for (const [index, line] of lines.entries()) {
|
|
44
|
+
if (continuation[index] === true) continue;
|
|
45
|
+
if (isTomlHeaderLine(line)) return undefined;
|
|
46
|
+
const separator = keyValueSeparator(line);
|
|
47
|
+
if (separator === undefined || tomlKeyName(line.slice(0, separator)) !== setting) continue;
|
|
48
|
+
const value = line.slice(separator + 1).match(/^\s*(?:"([^"]+)"|'([^']*)')/);
|
|
49
|
+
if (value !== null) return value[1] ?? value[2];
|
|
30
50
|
}
|
|
31
51
|
return undefined;
|
|
32
52
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "docks-kit",
|
|
3
|
-
"version": "0.22.
|
|
3
|
+
"version": "0.22.20",
|
|
4
4
|
"description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Claude Code, Codex, and universal agent skills",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -44,7 +44,7 @@
|
|
|
44
44
|
"lint:effect": "effect-tsgo diagnostics --project cli/tsconfig.json --strict --format text",
|
|
45
45
|
"format": "bun fmt --no-script cli/src cli/test cli/scripts vitest.config.ts",
|
|
46
46
|
"format:check": "bun fmt --no-script --check cli/src cli/test cli/scripts vitest.config.ts",
|
|
47
|
-
"check": "bun run --parallel lint lint:effect format:check typecheck test"
|
|
47
|
+
"check": "bun run --parallel lint lint:effect format:check typecheck check:generated test"
|
|
48
48
|
},
|
|
49
49
|
"dependencies": {
|
|
50
50
|
"@effect/platform-bun": "4.1.2",
|
|
@@ -1,163 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* The `docks-kit tidy --apply` lock. Only `node:` imports, so that a test child
|
|
3
|
-
* process can load this module alone.
|
|
4
|
-
*
|
|
5
|
-
* - The lock holds `<pid> <ISO time> <token>`, written with `wx`.
|
|
6
|
-
* - A lock is stale when its mtime is older than 1 h or its PID is dead.
|
|
7
|
-
* - Stale takeover runs only under the takeover mutex `<lock>.takeover`, and
|
|
8
|
-
* the holder checks staleness again before it removes the lock. Thus two
|
|
9
|
-
* runs never both remove a stale lock and both create a new one.
|
|
10
|
-
* - A run removes the lock and the mutex only while they still hold its token.
|
|
11
|
-
* - On Windows, another process can delete or hold the lock or the mutex while
|
|
12
|
-
* a run reads or removes it. Such a path counts as absent, and only the
|
|
13
|
-
* exclusive create decides the result.
|
|
14
|
-
*/
|
|
15
|
-
import { randomBytes } from "node:crypto";
|
|
16
|
-
import {
|
|
17
|
-
closeSync,
|
|
18
|
-
lstatSync,
|
|
19
|
-
openSync,
|
|
20
|
-
readFileSync,
|
|
21
|
-
unlinkSync,
|
|
22
|
-
writeSync,
|
|
23
|
-
type Stats,
|
|
24
|
-
} from "node:fs";
|
|
25
|
-
|
|
26
|
-
export const LOCK_STALE_MS = 3_600_000;
|
|
27
|
-
/** A takeover mutex lives for microseconds; one older than this belongs to a dead run. */
|
|
28
|
-
export const TAKEOVER_STALE_MS = 60_000;
|
|
29
|
-
|
|
30
|
-
export interface TidyLock {
|
|
31
|
-
readonly path: string;
|
|
32
|
-
readonly token: string;
|
|
33
|
-
}
|
|
34
|
-
|
|
35
|
-
function errorCode(cause: unknown): string | undefined {
|
|
36
|
-
return cause instanceof Error && "code" in cause && typeof cause.code === "string"
|
|
37
|
-
? cause.code
|
|
38
|
-
: undefined;
|
|
39
|
-
}
|
|
40
|
-
|
|
41
|
-
/**
|
|
42
|
-
* Windows keeps a deleted file "delete pending" while a handle to it is open,
|
|
43
|
-
* and refuses a new open of that name with ERROR_ACCESS_DENIED. A delete of a
|
|
44
|
-
* file that another process holds without delete sharing fails with
|
|
45
|
-
* ERROR_SHARING_VIOLATION. libuv, which runs the `node:fs` calls of Bun and
|
|
46
|
-
* Node.js on Windows, reports these errors as EPERM and EBUSY.
|
|
47
|
-
*/
|
|
48
|
-
const WINDOWS_CONTENTION: Record<string, true> = { EBUSY: true, EPERM: true };
|
|
49
|
-
|
|
50
|
-
/** True on Windows for an error that another process causes when it deletes or holds the path. */
|
|
51
|
-
function isWindowsContention(cause: unknown): boolean {
|
|
52
|
-
const code = errorCode(cause);
|
|
53
|
-
return process.platform === "win32" && code !== undefined && WINDOWS_CONTENTION[code] === true;
|
|
54
|
-
}
|
|
55
|
-
|
|
56
|
-
/**
|
|
57
|
-
* Create `path` with `wx` and write `text`. False when the path exists or, on
|
|
58
|
-
* Windows, when another process deletes it now.
|
|
59
|
-
*/
|
|
60
|
-
function createExclusive(path: string, text: string): boolean {
|
|
61
|
-
let fd: number;
|
|
62
|
-
try {
|
|
63
|
-
fd = openSync(path, "wx", 0o600);
|
|
64
|
-
} catch (cause) {
|
|
65
|
-
if (errorCode(cause) === "EEXIST" || isWindowsContention(cause)) return false;
|
|
66
|
-
throw cause;
|
|
67
|
-
}
|
|
68
|
-
try {
|
|
69
|
-
writeSync(fd, text);
|
|
70
|
-
} finally {
|
|
71
|
-
closeSync(fd);
|
|
72
|
-
}
|
|
73
|
-
return true;
|
|
74
|
-
}
|
|
75
|
-
|
|
76
|
-
/** `lstat`; `undefined` when absent or, on Windows, when another process deletes it. */
|
|
77
|
-
function lstatIfPresent(path: string): Stats | undefined {
|
|
78
|
-
try {
|
|
79
|
-
return lstatSync(path);
|
|
80
|
-
} catch (cause) {
|
|
81
|
-
const code = errorCode(cause);
|
|
82
|
-
if (code === "ENOENT" || code === "ENOTDIR" || isWindowsContention(cause)) return undefined;
|
|
83
|
-
throw cause;
|
|
84
|
-
}
|
|
85
|
-
}
|
|
86
|
-
|
|
87
|
-
function readText(path: string): string | undefined {
|
|
88
|
-
try {
|
|
89
|
-
return readFileSync(path, "utf8");
|
|
90
|
-
} catch {
|
|
91
|
-
return undefined;
|
|
92
|
-
}
|
|
93
|
-
}
|
|
94
|
-
|
|
95
|
-
/**
|
|
96
|
-
* Remove `path`. Ignore a path that is absent or, on Windows, a path that
|
|
97
|
-
* another process deletes or holds.
|
|
98
|
-
*/
|
|
99
|
-
function unlinkIfPresent(path: string): void {
|
|
100
|
-
try {
|
|
101
|
-
unlinkSync(path);
|
|
102
|
-
} catch (cause) {
|
|
103
|
-
if (errorCode(cause) !== "ENOENT" && !isWindowsContention(cause)) throw cause;
|
|
104
|
-
}
|
|
105
|
-
}
|
|
106
|
-
|
|
107
|
-
/** Remove `path` only while its third field is still `token`. */
|
|
108
|
-
function releaseOwned(path: string, token: string): void {
|
|
109
|
-
if (readText(path)?.trim().split(/\s+/)[2] !== token) return;
|
|
110
|
-
try {
|
|
111
|
-
unlinkSync(path);
|
|
112
|
-
} catch {
|
|
113
|
-
// The path is already gone.
|
|
114
|
-
}
|
|
115
|
-
}
|
|
116
|
-
|
|
117
|
-
/** True when the lock is absent, older than 1 h, or names a dead PID. */
|
|
118
|
-
function lockIsStale(path: string, now: number): boolean {
|
|
119
|
-
const stats = lstatIfPresent(path);
|
|
120
|
-
if (stats === undefined) return true;
|
|
121
|
-
if (now - stats.mtimeMs > LOCK_STALE_MS) return true;
|
|
122
|
-
const pid = Number.parseInt(readText(path)?.trim().split(/\s+/)[0] ?? "", 10);
|
|
123
|
-
if (!Number.isInteger(pid) || pid <= 0) return false;
|
|
124
|
-
try {
|
|
125
|
-
process.kill(pid, 0);
|
|
126
|
-
return false;
|
|
127
|
-
} catch (cause) {
|
|
128
|
-
return errorCode(cause) === "ESRCH";
|
|
129
|
-
}
|
|
130
|
-
}
|
|
131
|
-
|
|
132
|
-
/** Take the takeover mutex; remove a mutex older than 60 s once, then try once more. */
|
|
133
|
-
function acquireMutex(mutex: string, text: string, now: number): boolean {
|
|
134
|
-
if (createExclusive(mutex, text)) return true;
|
|
135
|
-
const seen = readText(mutex);
|
|
136
|
-
const stats = lstatIfPresent(mutex);
|
|
137
|
-
if (stats !== undefined && now - stats.mtimeMs <= TAKEOVER_STALE_MS) return false;
|
|
138
|
-
// Remove the stale mutex only while it still holds the text that this run saw.
|
|
139
|
-
if (stats !== undefined && readText(mutex) === seen) unlinkIfPresent(mutex);
|
|
140
|
-
return createExclusive(mutex, text);
|
|
141
|
-
}
|
|
142
|
-
|
|
143
|
-
/** Take the lock, or `undefined` when another run holds it. */
|
|
144
|
-
export function acquireTidyLock(path: string, now: number): TidyLock | undefined {
|
|
145
|
-
const token = randomBytes(16).toString("hex");
|
|
146
|
-
const text = `${process.pid} ${new Date(now).toISOString()} ${token}\n`;
|
|
147
|
-
if (createExclusive(path, text)) return { path, token };
|
|
148
|
-
if (!lockIsStale(path, now)) return undefined;
|
|
149
|
-
const mutex = `${path}.takeover`;
|
|
150
|
-
if (!acquireMutex(mutex, text, now)) return undefined;
|
|
151
|
-
try {
|
|
152
|
-
// Another run may have taken the lock over between the first check and the mutex.
|
|
153
|
-
if (!lockIsStale(path, now)) return undefined;
|
|
154
|
-
unlinkIfPresent(path);
|
|
155
|
-
return createExclusive(path, text) ? { path, token } : undefined;
|
|
156
|
-
} finally {
|
|
157
|
-
releaseOwned(mutex, token);
|
|
158
|
-
}
|
|
159
|
-
}
|
|
160
|
-
|
|
161
|
-
export function releaseTidyLock(lock: TidyLock): void {
|
|
162
|
-
releaseOwned(lock.path, lock.token);
|
|
163
|
-
}
|