docks-kit 0.22.13 → 0.22.22
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 +97 -83
- package/README.md +7 -7
- package/cli/docs/command-guards.md +12 -7
- package/cli/docs/flags.md +59 -9
- package/cli/docs/install.md +2 -2
- package/cli/docs/omp-context.md +27 -17
- package/cli/docs/omp-models.md +91 -70
- 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 +6 -4
- 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 +81 -88
- 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/harnesses.ts +5 -11
- package/cli/src/engine-native/index.ts +1 -1
- package/cli/src/engine-native/kitDb.ts +7 -7
- 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/ompOverlay.ts +23 -69
- package/cli/src/engine-native/ompPlugins.ts +23 -14
- package/cli/src/engine-native/ompRemovals.ts +97 -30
- package/cli/src/engine-native/ompSync.ts +66 -32
- 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/sharedTypes.d.ts +0 -2
- 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
|
@@ -1,24 +1,23 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* EngineNative kit
|
|
3
|
-
*
|
|
4
|
-
*
|
|
2
|
+
* EngineNative kit skill prune (`--prune` reconcile against the owned record
|
|
3
|
+
* of `skillsRecords.ts`). Split from skillsSync.ts; the orchestration still
|
|
4
|
+
* lives there.
|
|
5
5
|
*
|
|
6
6
|
* The prune deletes only what the kit created: the canonical skill directory
|
|
7
|
-
* and the kit-managed Claude entry. It
|
|
8
|
-
*
|
|
7
|
+
* of a slug in `.kit-owned-skills` and the kit-managed Claude entry. It
|
|
8
|
+
* removes a canonical directory only while it keeps the `<dev>:<ino>` that
|
|
9
|
+
* the owned record names. It does not call `skills remove`, because that
|
|
10
|
+
* command deletes the same-named directory of every known agent. A slug that
|
|
11
|
+
* only the legacy `.kit-managed-skills` names is kept with a message, because
|
|
12
|
+
* an older kit also recorded directories that the user made.
|
|
9
13
|
*/
|
|
10
|
-
import { existsSync,
|
|
11
|
-
import { p
|
|
14
|
+
import { existsSync, rmSync } from "node:fs";
|
|
15
|
+
import { p } from "./exec";
|
|
12
16
|
import type { Ctx } from "./index";
|
|
13
17
|
import { compareCodepoints } from "./jq";
|
|
14
18
|
import { isKitOwnedCopy, lstat, removeKitOwnedCopy, removeLink } from "./skillsLinks";
|
|
15
19
|
import { normalizeManifest, skillBase } from "./skillsManifest";
|
|
16
|
-
|
|
17
|
-
// ----------------------------------------------------- prune + snapshot ----
|
|
18
|
-
|
|
19
|
-
export function readSlugs(file: string): Array<string> {
|
|
20
|
-
return existsSync(file) ? normalizeManifest(readFileSync(file, "utf8")) : [];
|
|
21
|
-
}
|
|
20
|
+
import { directoryIdentity, type SkillRecords } from "./skillsRecords";
|
|
22
21
|
|
|
23
22
|
function removeCanonical(path: string): boolean {
|
|
24
23
|
try {
|
|
@@ -29,30 +28,54 @@ function removeCanonical(path: string): boolean {
|
|
|
29
28
|
}
|
|
30
29
|
}
|
|
31
30
|
|
|
32
|
-
|
|
31
|
+
/**
|
|
32
|
+
* Removes each owned skill that the SoT no longer declares, and drops it from
|
|
33
|
+
* `records.owned` (in memory). A failed removal keeps the slug, so the next
|
|
34
|
+
* prune tries again. An owned slug whose directory is not the one that the
|
|
35
|
+
* kit installed is kept with a line. It leaves the record, so the line prints
|
|
36
|
+
* once. A legacy slug that the SoT dropped gets a keep line while its
|
|
37
|
+
* canonical path still has an entry. Only the legacy record names it, so the
|
|
38
|
+
* kit keeps it.
|
|
39
|
+
*/
|
|
40
|
+
export function reconcileRemovals(ctx: Ctx, manifest: string, records: SkillRecords): void {
|
|
33
41
|
const { change, echo, warn } = ctx.services.logger;
|
|
34
|
-
if (!existsSync(
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
);
|
|
39
|
-
}
|
|
40
|
-
return [];
|
|
42
|
+
if (ctx.dryRun && !existsSync(records.ownedFile)) {
|
|
43
|
+
echo(
|
|
44
|
+
`[dry-run] (--prune) no kit-owned-skills record yet; a sync writes ${records.ownedFile} when it installs a skill, and --prune removes only the skills that it names`,
|
|
45
|
+
);
|
|
41
46
|
}
|
|
42
47
|
|
|
43
48
|
const current = normalizeManifest(manifest);
|
|
44
49
|
const currentBases = new Set(current.map(skillBase));
|
|
50
|
+
const declared = (slug: string): boolean =>
|
|
51
|
+
current.includes(slug) || currentBases.has(skillBase(slug));
|
|
52
|
+
|
|
53
|
+
for (const slug of [...records.legacy].sort(compareCodepoints)) {
|
|
54
|
+
if (declared(slug) || records.owned.has(slug)) continue;
|
|
55
|
+
if (lstat(p(ctx.agentsDir, "skills", skillBase(slug))) === undefined) continue;
|
|
56
|
+
warn(
|
|
57
|
+
`keep ${slug}: an older kit recorded it, so the kit cannot prove it installed it; remove it by hand if the kit did`,
|
|
58
|
+
);
|
|
59
|
+
}
|
|
60
|
+
|
|
45
61
|
let removed = 0;
|
|
46
62
|
let failed = 0;
|
|
47
|
-
const
|
|
48
|
-
|
|
49
|
-
if (current.includes(slug)) continue;
|
|
63
|
+
for (const slug of [...records.owned.keys()].sort(compareCodepoints)) {
|
|
64
|
+
if (declared(slug)) continue;
|
|
50
65
|
const base = skillBase(slug);
|
|
51
|
-
if (currentBases.has(base)) continue;
|
|
52
66
|
const canonical = p(ctx.agentsDir, "skills", base);
|
|
53
|
-
// The skills CLI installs a canonical skill as a real directory that holds
|
|
67
|
+
// The skills CLI installs a canonical skill as a real directory that holds
|
|
68
|
+
// SKILL.md. A gone directory needs only the Claude entry cleanup.
|
|
69
|
+
const canonicalStat = lstat(canonical);
|
|
54
70
|
const installedCanonical =
|
|
55
|
-
|
|
71
|
+
canonicalStat?.isDirectory() === true &&
|
|
72
|
+
existsSync(p(canonical, "SKILL.md")) &&
|
|
73
|
+
directoryIdentity(canonical) === records.owned.get(slug);
|
|
74
|
+
if (canonicalStat !== undefined && !installedCanonical) {
|
|
75
|
+
warn(`keep ${slug}: the directory is not the one that the kit installed`);
|
|
76
|
+
if (!ctx.dryRun) records.owned.delete(slug);
|
|
77
|
+
continue;
|
|
78
|
+
}
|
|
56
79
|
const claudeEntry = p(ctx.home, ".claude", "skills", base);
|
|
57
80
|
const managedClaudeEntry =
|
|
58
81
|
lstat(claudeEntry)?.isSymbolicLink() === true || isKitOwnedCopy(claudeEntry);
|
|
@@ -66,7 +89,6 @@ export function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string):
|
|
|
66
89
|
if (installedCanonical && !removeCanonical(canonical)) {
|
|
67
90
|
warn(`Failed to remove kit-managed skill: ${base}`);
|
|
68
91
|
failed++;
|
|
69
|
-
failedSlugs.push(slug);
|
|
70
92
|
continue;
|
|
71
93
|
}
|
|
72
94
|
if (managedClaudeEntry) {
|
|
@@ -77,10 +99,10 @@ export function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string):
|
|
|
77
99
|
if (!removedClaudeEntry) {
|
|
78
100
|
warn(`Failed to remove kit-managed Claude skill entry: ${base}`);
|
|
79
101
|
failed++;
|
|
80
|
-
failedSlugs.push(slug);
|
|
81
102
|
continue;
|
|
82
103
|
}
|
|
83
104
|
}
|
|
105
|
+
records.owned.delete(slug);
|
|
84
106
|
removed++;
|
|
85
107
|
}
|
|
86
108
|
|
|
@@ -92,24 +114,4 @@ export function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string):
|
|
|
92
114
|
warn(
|
|
93
115
|
`${failed} skill remove(s) failed — re-run with --prune, or delete ~/.agents/skills/<name> and the ~/.claude/skills/<name> link manually`,
|
|
94
116
|
);
|
|
95
|
-
return failedSlugs;
|
|
96
|
-
}
|
|
97
|
-
|
|
98
|
-
/**
|
|
99
|
-
* Writes the declared slugs plus `retainedSlugs`. A slug leaves the snapshot
|
|
100
|
-
* only after a successful --prune removes it.
|
|
101
|
-
*/
|
|
102
|
-
export function updateSnapshot(
|
|
103
|
-
ctx: Ctx,
|
|
104
|
-
manifest: string,
|
|
105
|
-
snapshot: string,
|
|
106
|
-
retainedSlugs: ReadonlyArray<string>,
|
|
107
|
-
): void {
|
|
108
|
-
if (ctx.dryRun) return;
|
|
109
|
-
|
|
110
|
-
mkdirSync(ctx.agentsDir, { recursive: true });
|
|
111
|
-
const sorted = [...new Set([...normalizeManifest(manifest), ...retainedSlugs])].sort(
|
|
112
|
-
compareCodepoints,
|
|
113
|
-
);
|
|
114
|
-
writeTextIfChanged(snapshot, sorted.length > 0 ? `${sorted.join("\n")}\n` : "");
|
|
115
117
|
}
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* EngineNative skill ownership records under `~/.agents`:
|
|
3
|
+
* - `.kit-pending-skills`, one slug per line: a slug whose install runs. Sync
|
|
4
|
+
* adds it before `npx skills add` only when the canonical skill directory
|
|
5
|
+
* does not exist. So it never names a directory that existed before the
|
|
6
|
+
* install.
|
|
7
|
+
* - `.kit-owned-skills`, one `<slug>\t<dev>:<ino>` line per skill: the skills
|
|
8
|
+
* that the kit installed, with the identity of the directory that the
|
|
9
|
+
* install created. It is the only record that lets `--prune` remove a
|
|
10
|
+
* skill, and only while the directory keeps that identity.
|
|
11
|
+
* - `.kit-managed-skills`: the legacy snapshot. An older kit also recorded
|
|
12
|
+
* directories that the user made there, so sync reads it and never writes
|
|
13
|
+
* it, and its entries never let `--prune` remove a skill.
|
|
14
|
+
*
|
|
15
|
+
* After each install, sync writes the owned record before the slug leaves the
|
|
16
|
+
* pending record, and before the next install starts. So a sync that stops at
|
|
17
|
+
* any point leaves each installed slug in one of the two records. The next
|
|
18
|
+
* sync moves a leftover pending slug to the owned record when its directory
|
|
19
|
+
* exists, and drops it otherwise.
|
|
20
|
+
*/
|
|
21
|
+
import { existsSync, lstatSync, readFileSync, rmSync } from "node:fs";
|
|
22
|
+
import { replaceTextIfChanged } from "./atomicWrite";
|
|
23
|
+
import { p } from "./exec";
|
|
24
|
+
import type { Ctx } from "./index";
|
|
25
|
+
import { compareCodepoints } from "./jq";
|
|
26
|
+
import { isDir, lstat } from "./skillsLinks";
|
|
27
|
+
import { normalizeManifest, skillBase } from "./skillsManifest";
|
|
28
|
+
|
|
29
|
+
export interface SkillRecords {
|
|
30
|
+
readonly ownedFile: string;
|
|
31
|
+
readonly pendingFile: string;
|
|
32
|
+
readonly legacyFile: string;
|
|
33
|
+
/** Each owned slug and the `<dev>:<ino>` identity of the directory that its install created. */
|
|
34
|
+
readonly owned: Map<string, string>;
|
|
35
|
+
readonly pending: Set<string>;
|
|
36
|
+
readonly legacy: ReadonlySet<string>;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** The `<dev>:<ino>` identity of the entry at `path`, or undefined when no entry exists. */
|
|
40
|
+
export function directoryIdentity(path: string): string | undefined {
|
|
41
|
+
// bigint keeps a Windows file index exact; a number loses digits above 2^53.
|
|
42
|
+
const stats = lstatSync(path, { bigint: true, throwIfNoEntry: false });
|
|
43
|
+
return stats === undefined ? undefined : `${stats.dev}:${stats.ino}`;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function readSlugs(file: string): Set<string> {
|
|
47
|
+
return new Set(existsSync(file) ? normalizeManifest(readFileSync(file, "utf8")) : []);
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Read the owned record. A line with no identity keeps the slug with an empty
|
|
52
|
+
* identity, which matches no directory, so it never lets `--prune` remove one.
|
|
53
|
+
*/
|
|
54
|
+
function readOwned(file: string): Map<string, string> {
|
|
55
|
+
const owned = new Map<string, string>();
|
|
56
|
+
if (!existsSync(file)) return owned;
|
|
57
|
+
for (const line of readFileSync(file, "utf8").split("\n")) {
|
|
58
|
+
const [slug = "", identity = ""] = line.trim().split("\t");
|
|
59
|
+
if (slug !== "") owned.set(slug, identity);
|
|
60
|
+
}
|
|
61
|
+
return owned;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function slugLines(slugs: ReadonlySet<string>): string {
|
|
65
|
+
const sorted = [...slugs].sort(compareCodepoints);
|
|
66
|
+
return sorted.length > 0 ? `${sorted.join("\n")}\n` : "";
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
function ownedLines(owned: ReadonlyMap<string, string>): string {
|
|
70
|
+
const slugs = [...owned.keys()].sort(compareCodepoints);
|
|
71
|
+
return slugs.map((slug) => `${slug}\t${owned.get(slug) ?? ""}\n`).join("");
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
export function readSkillRecords(agentsDir: string): SkillRecords {
|
|
75
|
+
const ownedFile = p(agentsDir, ".kit-owned-skills");
|
|
76
|
+
const pendingFile = p(agentsDir, ".kit-pending-skills");
|
|
77
|
+
const legacyFile = p(agentsDir, ".kit-managed-skills");
|
|
78
|
+
return {
|
|
79
|
+
ownedFile,
|
|
80
|
+
pendingFile,
|
|
81
|
+
legacyFile,
|
|
82
|
+
owned: readOwned(ownedFile),
|
|
83
|
+
pending: readSlugs(pendingFile),
|
|
84
|
+
legacy: readSlugs(legacyFile),
|
|
85
|
+
};
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/** True when the canonical skill directory of `slug` has no entry, so an install creates it. */
|
|
89
|
+
export function canonicalAbsent(skillsDir: string, slug: string): boolean {
|
|
90
|
+
return lstat(p(skillsDir, skillBase(slug))) === undefined;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* Ends the pending state of `slug`. When its canonical directory exists, the
|
|
95
|
+
* slug moves to the owned record with the identity of that directory. Else it
|
|
96
|
+
* leaves the pending record. A slug that the owned record already names keeps
|
|
97
|
+
* its identity. A sync that stopped between the two record writes leaves the
|
|
98
|
+
* slug in both records, and the directory can change before the next sync.
|
|
99
|
+
* Changes the records in memory only; `writeSkillRecords` writes them.
|
|
100
|
+
*/
|
|
101
|
+
export function settlePendingSlug(records: SkillRecords, skillsDir: string, slug: string): void {
|
|
102
|
+
if (!records.pending.delete(slug) || records.owned.has(slug)) return;
|
|
103
|
+
const canonical = p(skillsDir, skillBase(slug));
|
|
104
|
+
const identity = isDir(canonical) ? directoryIdentity(canonical) : undefined;
|
|
105
|
+
if (identity !== undefined) records.owned.set(slug, identity);
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* Records `slug` as pending and writes the pending record before its install
|
|
110
|
+
* starts. The canonical directory is gone, so an owned identity of the slug is
|
|
111
|
+
* stale. It leaves the owned record first, so the install can record the new
|
|
112
|
+
* directory.
|
|
113
|
+
*/
|
|
114
|
+
export function recordPendingInstall(records: SkillRecords, slug: string): void {
|
|
115
|
+
if (records.owned.delete(slug)) {
|
|
116
|
+
replaceTextIfChanged(records.ownedFile, ownedLines(records.owned));
|
|
117
|
+
}
|
|
118
|
+
records.pending.add(slug);
|
|
119
|
+
replaceTextIfChanged(records.pendingFile, slugLines(records.pending));
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* Writes the owned record, then the pending record, so a sync that stops
|
|
124
|
+
* between the two writes keeps the pending slugs for the next sync. An empty
|
|
125
|
+
* pending record is removed. Writes nothing under dry run.
|
|
126
|
+
*/
|
|
127
|
+
export function writeSkillRecords(ctx: Ctx, records: SkillRecords): void {
|
|
128
|
+
if (ctx.dryRun) return;
|
|
129
|
+
const owned = ownedLines(records.owned);
|
|
130
|
+
if (owned !== "" || existsSync(records.ownedFile)) {
|
|
131
|
+
replaceTextIfChanged(records.ownedFile, owned);
|
|
132
|
+
}
|
|
133
|
+
if (records.pending.size > 0) {
|
|
134
|
+
replaceTextIfChanged(records.pendingFile, slugLines(records.pending));
|
|
135
|
+
} else {
|
|
136
|
+
rmSync(records.pendingFile, { force: true });
|
|
137
|
+
}
|
|
138
|
+
}
|
|
@@ -1,20 +1,21 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* EngineNative `sync agents` pipeline: universal-skill bootstrap
|
|
3
3
|
* (`npx skills@<pin> add`), Claude symlink healing, --prune reconcile against
|
|
4
|
-
* the kit-
|
|
4
|
+
* the kit-owned record, and the record writes.
|
|
5
5
|
*
|
|
6
6
|
* Split: manifest parsing lives in `skillsManifest.ts`, link mechanics and
|
|
7
|
-
* healing in `skillsLinks.ts`, the install pass in `skillsInstall.ts`,
|
|
8
|
-
*
|
|
9
|
-
* orchestration and re-exports the public surface so
|
|
10
|
-
* keep working.
|
|
7
|
+
* healing in `skillsLinks.ts`, the install pass in `skillsInstall.ts`, the
|
|
8
|
+
* ownership records in `skillsRecords.ts`, and the prune in `skillsPrune.ts`.
|
|
9
|
+
* This module keeps the orchestration and re-exports the public surface so
|
|
10
|
+
* existing import paths keep working.
|
|
11
11
|
*/
|
|
12
12
|
import { mkdirSync } from "node:fs";
|
|
13
13
|
import { payloadText } from "../payload";
|
|
14
14
|
import { p } from "./exec";
|
|
15
15
|
import type { Ctx } from "./index";
|
|
16
16
|
import { syncUniversal, type SkillsState } from "./skillsInstall";
|
|
17
|
-
import {
|
|
17
|
+
import { reconcileRemovals } from "./skillsPrune";
|
|
18
|
+
import { readSkillRecords, settlePendingSlug, writeSkillRecords } from "./skillsRecords";
|
|
18
19
|
|
|
19
20
|
export type { SkillsState } from "./skillsInstall";
|
|
20
21
|
export { COPY_MARKER, linkOrCopy, type LinkOutcome } from "./skillsLinks";
|
|
@@ -24,16 +25,18 @@ export async function skillsSync(ctx: Ctx): Promise<SkillsState> {
|
|
|
24
25
|
const state: SkillsState = { present: 0 };
|
|
25
26
|
const skillsDir = p(ctx.agentsDir, "skills");
|
|
26
27
|
const manifest = payloadText("SoT/.agents/skills.txt");
|
|
27
|
-
const
|
|
28
|
+
const records = readSkillRecords(ctx.agentsDir);
|
|
28
29
|
|
|
29
30
|
if (!ctx.dryRun) mkdirSync(skillsDir, { recursive: true });
|
|
30
31
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
32
|
+
// A pending slug that an earlier sync left: its install ran, but its record did not.
|
|
33
|
+
for (const slug of [...records.pending]) settlePendingSlug(records, skillsDir, slug);
|
|
34
|
+
writeSkillRecords(ctx, records);
|
|
35
|
+
|
|
36
|
+
await syncUniversal(ctx, state, skillsDir, manifest, records);
|
|
37
|
+
// An owned slug leaves the record only after a successful --prune removes it.
|
|
38
|
+
if (ctx.prune) reconcileRemovals(ctx, manifest, records);
|
|
39
|
+
writeSkillRecords(ctx, records);
|
|
37
40
|
return state;
|
|
38
41
|
}
|
|
39
42
|
|
|
@@ -4,14 +4,28 @@
|
|
|
4
4
|
* Split from index.ts; the `sync`/`model`/`toolchain` entry routing still
|
|
5
5
|
* lives there.
|
|
6
6
|
*/
|
|
7
|
+
import { existsSync, mkdirSync, realpathSync } from "node:fs";
|
|
8
|
+
import { basename, dirname, join, resolve } from "node:path";
|
|
9
|
+
|
|
7
10
|
import { payloadText } from "../payload";
|
|
8
11
|
import { claudeNextSteps, claudeSummary, claudeSync, type ClaudeRuntimeState } from "./claudeSync";
|
|
9
12
|
import { preflightClaudeSettings } from "./claudeSettings";
|
|
13
|
+
import { codexHome } from "./codexPaths";
|
|
10
14
|
import { codexNextSteps, codexSummary, codexSync } from "./codexSync";
|
|
11
15
|
import type { Ctx } from "./index";
|
|
12
|
-
import {
|
|
16
|
+
import { compareCodepoints } from "./jq";
|
|
17
|
+
import { acquireKitLock, releaseKitLock, type KitLock } from "./kitLock";
|
|
18
|
+
import {
|
|
19
|
+
ompNextSteps,
|
|
20
|
+
ompSummary,
|
|
21
|
+
ompSync,
|
|
22
|
+
ompWriteFolders,
|
|
23
|
+
type OmpState,
|
|
24
|
+
type OmpWriteFolders,
|
|
25
|
+
} from "./ompSync";
|
|
13
26
|
import { skillsNextSteps, skillsSummary, skillsSync, type SkillsState } from "./skillsSync";
|
|
14
27
|
import { ExitError, parseArgs, validateModifierFlags } from "./parseArgs";
|
|
28
|
+
import { folderSyncLockPath, syncLockPath } from "./scratch";
|
|
15
29
|
import {
|
|
16
30
|
runBounded,
|
|
17
31
|
syncConcurrencyForManifest,
|
|
@@ -19,8 +33,158 @@ import {
|
|
|
19
33
|
type SyncTask,
|
|
20
34
|
} from "./syncConcurrency";
|
|
21
35
|
|
|
36
|
+
/** The default time that a sync or a model write waits for another sync to release the sync lock. */
|
|
37
|
+
export const SYNC_LOCK_WAIT_MS = 120_000;
|
|
38
|
+
const SYNC_LOCK_WAIT_ERROR = "DOCKS_KIT_SYNC_LOCK_WAIT_MS must be a non-negative safe integer";
|
|
39
|
+
|
|
40
|
+
/** Print one error line, as `Logger.err` does. */
|
|
41
|
+
type ErrorSink = (message: string) => void;
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* The sync lock wait bound: `DOCKS_KIT_SYNC_LOCK_WAIT_MS` in ms, or
|
|
45
|
+
* `SYNC_LOCK_WAIT_MS` when unset or empty. A value above
|
|
46
|
+
* `Number.MAX_SAFE_INTEGER` exits 2: `Number` would round it or make it
|
|
47
|
+
* Infinity, and an Infinity wait never ends.
|
|
48
|
+
*/
|
|
49
|
+
function syncLockWaitMs(err: ErrorSink): number {
|
|
50
|
+
const configured = process.env["DOCKS_KIT_SYNC_LOCK_WAIT_MS"];
|
|
51
|
+
if (configured === undefined || configured === "") return SYNC_LOCK_WAIT_MS;
|
|
52
|
+
if (/^\d+$/.test(configured) && Number.isSafeInteger(Number(configured))) {
|
|
53
|
+
return Number(configured);
|
|
54
|
+
}
|
|
55
|
+
err(SYNC_LOCK_WAIT_ERROR);
|
|
56
|
+
throw new ExitError(2);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* The tokens that skip the sync lock. `-h` and `--help` make `parseArgs`
|
|
61
|
+
* print the usage or an error and exit before it reads `kit.db`. A
|
|
62
|
+
* `--dry-run` sync writes no kit file except a `kit.db` migration, which
|
|
63
|
+
* `kitDb.ts` makes safe for parallel runs.
|
|
64
|
+
*/
|
|
65
|
+
const UNLOCKED_TOKENS: Record<string, true> = { "--dry-run": true, "-h": true, "--help": true };
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Run `body` under each lock of `paths`, taken in that order. When another
|
|
69
|
+
* sync keeps a lock past the wait bound, print the held line and return 1
|
|
70
|
+
* without a call to `body`. Each taken lock goes when the run ends, also when
|
|
71
|
+
* it throws; the OS releases the locks when the process ends.
|
|
72
|
+
*
|
|
73
|
+
* With `privateDirectory` false, each path is a folder lock. A missing folder
|
|
74
|
+
* is created just before its lock, so the locks of its ancestors in the set
|
|
75
|
+
* are already held. Each folder that this creates gets mode 0700, as
|
|
76
|
+
* `ompFileDeploy.ts ensureDirectory` gives the parents of an omp folder. An
|
|
77
|
+
* existing folder keeps its mode: `mkdirSync` applies `mode` only to the
|
|
78
|
+
* folders that it creates.
|
|
79
|
+
*/
|
|
80
|
+
async function withKitLocks(
|
|
81
|
+
err: ErrorSink,
|
|
82
|
+
paths: ReadonlyArray<string>,
|
|
83
|
+
privateDirectory: boolean,
|
|
84
|
+
body: () => Promise<number>,
|
|
85
|
+
): Promise<number> {
|
|
86
|
+
const waitMs = syncLockWaitMs(err);
|
|
87
|
+
const held: Array<KitLock> = [];
|
|
88
|
+
try {
|
|
89
|
+
for (const path of paths) {
|
|
90
|
+
if (!privateDirectory) mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
|
|
91
|
+
const result = await acquireKitLock(path, { waitMs, privateDirectory });
|
|
92
|
+
if (result.kind === "held") {
|
|
93
|
+
err(`another docks-kit sync holds ${path}; run sync again after it ends`);
|
|
94
|
+
return 1;
|
|
95
|
+
}
|
|
96
|
+
held.push(result.lock);
|
|
97
|
+
}
|
|
98
|
+
return await body();
|
|
99
|
+
} finally {
|
|
100
|
+
for (const lock of held.reverse()) releaseKitLock(lock);
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* Run `body` under the sync lock `syncLockPath(ctx.home)`. Two syncs of the
|
|
106
|
+
* same home meet at this lock. A dry run takes no lock: `args` holds one of
|
|
107
|
+
* `UNLOCKED_TOKENS`, or `ctx.dryRun` is true. `makeCtx` sets `ctx.dryRun`
|
|
108
|
+
* from the `DRY_RUN` env global only on the channel that reads env globals.
|
|
109
|
+
*/
|
|
110
|
+
export async function withSyncLock(
|
|
111
|
+
ctx: Ctx,
|
|
112
|
+
args: ReadonlyArray<string>,
|
|
113
|
+
body: () => Promise<number>,
|
|
114
|
+
): Promise<number> {
|
|
115
|
+
if (ctx.dryRun || args.some((arg) => Object.hasOwn(UNLOCKED_TOKENS, arg))) return await body();
|
|
116
|
+
return await withKitLocks(ctx.services.logger.err, [syncLockPath(ctx.home)], true, body);
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* The canonical path of `folder`, which can be missing: the real path of its
|
|
121
|
+
* nearest existing ancestor, joined with the rest of the path.
|
|
122
|
+
*/
|
|
123
|
+
function canonicalFolder(folder: string): string {
|
|
124
|
+
const missing: Array<string> = [];
|
|
125
|
+
let current = folder;
|
|
126
|
+
while (!existsSync(current) && dirname(current) !== current) {
|
|
127
|
+
missing.unshift(basename(current));
|
|
128
|
+
current = dirname(current);
|
|
129
|
+
}
|
|
130
|
+
return join(realpathSync.native(current), ...missing);
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* The folder lock path of each folder, by the canonical path of the folder,
|
|
135
|
+
* with no duplicates, sorted by folder. Every sync takes its folder locks in
|
|
136
|
+
* this order, so no two syncs can wait on each other in a cycle. An ancestor
|
|
137
|
+
* sorts before its descendants, and a nested folder keeps its own lock.
|
|
138
|
+
*/
|
|
139
|
+
export function folderLockPaths(folders: ReadonlyArray<string>): Array<string> {
|
|
140
|
+
const canonical = new Set(folders.map(canonicalFolder));
|
|
141
|
+
return [...canonical].sort(compareCodepoints).map(folderSyncLockPath);
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/**
|
|
145
|
+
* Run `body` under the folder lock of each folder in `folders`. Take it after
|
|
146
|
+
* the sync lock. Syncs of different homes can share a Codex, agents, or omp
|
|
147
|
+
* folder, and their home locks differ. A missing folder is created under the
|
|
148
|
+
* locks of its ancestors in the set. A dry run takes no folder lock and
|
|
149
|
+
* creates nothing.
|
|
150
|
+
*/
|
|
151
|
+
export async function withFolderLocks(
|
|
152
|
+
ctx: Ctx,
|
|
153
|
+
folders: ReadonlyArray<string>,
|
|
154
|
+
body: () => Promise<number>,
|
|
155
|
+
): Promise<number> {
|
|
156
|
+
if (ctx.dryRun) return await body();
|
|
157
|
+
return await withKitLocks(ctx.services.logger.err, folderLockPaths(folders), false, body);
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/**
|
|
161
|
+
* Run `body` under the sync lock of `home` and the folder locks of `folders`,
|
|
162
|
+
* with the wait and the held line of a sync. A command that writes a sync
|
|
163
|
+
* file outside a sync run uses it. Print each error line with `err`.
|
|
164
|
+
*/
|
|
165
|
+
export async function withHomeAndFolderLocks(
|
|
166
|
+
home: string,
|
|
167
|
+
folders: ReadonlyArray<string>,
|
|
168
|
+
err: ErrorSink,
|
|
169
|
+
body: () => Promise<number>,
|
|
170
|
+
): Promise<number> {
|
|
171
|
+
return await withKitLocks(err, [syncLockPath(home)], true, () =>
|
|
172
|
+
withKitLocks(err, folderLockPaths(folders), false, body),
|
|
173
|
+
);
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
/**
|
|
177
|
+
* Run a sync. The sync lock comes first: `parseArgs` reads the harness
|
|
178
|
+
* selection from `kit.db`, and that read can migrate `kit.db` and rename a
|
|
179
|
+
* legacy `state.json`. The folder locks come after `parseArgs` selects the
|
|
180
|
+
* targets.
|
|
181
|
+
*/
|
|
22
182
|
export async function engineSync(ctx: Ctx, args: ReadonlyArray<string>): Promise<number> {
|
|
23
|
-
|
|
183
|
+
return await withSyncLock(ctx, args, () => runSync(ctx, args));
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
async function runSync(ctx: Ctx, args: ReadonlyArray<string>): Promise<number> {
|
|
187
|
+
const { err } = ctx.services.logger;
|
|
24
188
|
parseArgs(ctx, args);
|
|
25
189
|
await validateModifierFlags(ctx);
|
|
26
190
|
const configuredConcurrency = process.env["DOCKS_KIT_SYNC_CONCURRENCY"];
|
|
@@ -36,6 +200,24 @@ export async function engineSync(ctx: Ctx, args: ReadonlyArray<string>): Promise
|
|
|
36
200
|
err("DOCKS_KIT_SYNC_CONCURRENCY must be 1, 2, or 3");
|
|
37
201
|
throw new ExitError(2);
|
|
38
202
|
}
|
|
203
|
+
|
|
204
|
+
// The folders that hold ownership records or omp files. A writing pipeline
|
|
205
|
+
// creates its folders anyway, so `withFolderLocks` creates each missing one
|
|
206
|
+
// under the locks of its ancestors in the set. The omp folders are resolved
|
|
207
|
+
// once, here: the omp pipeline and its omp children use these paths, so a
|
|
208
|
+
// data root that appears after the locks cannot move them.
|
|
209
|
+
const omp = ctx.syncOmp ? ompWriteFolders(ctx) : undefined;
|
|
210
|
+
const folders = [
|
|
211
|
+
...(ctx.syncCodex ? [codexHome(ctx.home)] : []),
|
|
212
|
+
...(ctx.syncAgents ? [resolve(ctx.agentsDir)] : []),
|
|
213
|
+
...(omp === undefined ? [] : [omp.paths.agentDir, omp.intercomDir, omp.paths.dataRoot]),
|
|
214
|
+
];
|
|
215
|
+
return await withFolderLocks(ctx, folders, () => runPipelines(ctx, omp));
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
/** Run the selected pipelines. `omp` holds the omp folders when omp is selected. */
|
|
219
|
+
async function runPipelines(ctx: Ctx, omp: OmpWriteFolders | undefined): Promise<number> {
|
|
220
|
+
const { acquireTerminal, echo } = ctx.services.logger;
|
|
39
221
|
// An abort-class check runs before any pipeline starts, so the abort stops the whole sync.
|
|
40
222
|
preflightClaudeSettings(ctx);
|
|
41
223
|
|
|
@@ -71,10 +253,10 @@ export async function engineSync(ctx: Ctx, args: ReadonlyArray<string>): Promise
|
|
|
71
253
|
run: async () => ({ kind: "skills", state: await skillsSync(ctx) }),
|
|
72
254
|
});
|
|
73
255
|
}
|
|
74
|
-
if (
|
|
256
|
+
if (omp !== undefined) {
|
|
75
257
|
selected.push({
|
|
76
258
|
name: "omp",
|
|
77
|
-
run: async () => ({ kind: "omp", state: await ompSync(ctx) }),
|
|
259
|
+
run: async () => ({ kind: "omp", state: await ompSync(ctx, omp) }),
|
|
78
260
|
});
|
|
79
261
|
}
|
|
80
262
|
|