docks-kit 0.22.28 → 0.24.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.
Files changed (93) hide show
  1. package/AGENTS.md +42 -89
  2. package/README.md +35 -72
  3. package/cli/docs/command-guards.md +233 -197
  4. package/cli/docs/flags.md +17 -65
  5. package/cli/docs/install.md +2 -3
  6. package/cli/docs/omp-context.md +79 -7
  7. package/cli/docs/omp-models.md +27 -12
  8. package/cli/docs/overview.md +7 -18
  9. package/cli/docs/platforms.md +2 -2
  10. package/cli/docs/sync-layers.md +14 -60
  11. package/cli/docs/toolchain.md +12 -81
  12. package/cli/src/argv.ts +0 -12
  13. package/cli/src/argvValidate.ts +3 -54
  14. package/cli/src/commands/docs.ts +3 -15
  15. package/cli/src/commands/omp.ts +1 -1
  16. package/cli/src/commands/scratch.ts +1 -1
  17. package/cli/src/commands/sync.ts +5 -120
  18. package/cli/src/commands/tidy.ts +1 -1
  19. package/cli/src/commands/toolchain.ts +4 -12
  20. package/cli/src/engine-native/DESIGN.md +69 -100
  21. package/cli/src/engine-native/deps.ts +7 -92
  22. package/cli/src/engine-native/engineCtx.ts +9 -103
  23. package/cli/src/engine-native/exec.ts +1 -18
  24. package/cli/src/engine-native/index.ts +6 -8
  25. package/cli/src/engine-native/jq.ts +4 -37
  26. package/cli/src/engine-native/kitDb.ts +21 -37
  27. package/cli/src/engine-native/modes.ts +3 -132
  28. package/cli/src/engine-native/ompFastMode.ts +1 -1
  29. package/cli/src/engine-native/ompOverlay.ts +1 -1
  30. package/cli/src/engine-native/ompRemovals.ts +24 -3
  31. package/cli/src/engine-native/ompSession.ts +67 -0
  32. package/cli/src/engine-native/ompSync.ts +1 -1
  33. package/cli/src/engine-native/os/darwin.ts +0 -4
  34. package/cli/src/engine-native/os/index.ts +1 -2
  35. package/cli/src/engine-native/os/linux.ts +0 -3
  36. package/cli/src/engine-native/os/posix.ts +2 -47
  37. package/cli/src/engine-native/os/types.ts +1 -36
  38. package/cli/src/engine-native/os/windows.ts +0 -50
  39. package/cli/src/engine-native/parseArgs.ts +7 -180
  40. package/cli/src/engine-native/parseHelp.ts +4 -44
  41. package/cli/src/engine-native/scratch.ts +1 -1
  42. package/cli/src/engine-native/services.ts +1 -2
  43. package/cli/src/engine-native/sharedTypes.d.ts +1 -41
  44. package/cli/src/engine-native/syncConcurrency.ts +3 -15
  45. package/cli/src/engine-native/syncDispatch.ts +30 -143
  46. package/cli/src/engine-native/toolchain.ts +6 -45
  47. package/cli/src/engine.ts +0 -75
  48. package/cli/src/generated/sotPayload.ts +14 -43
  49. package/cli/src/main.ts +8 -24
  50. package/cli/src/payload.ts +2 -8
  51. package/cli/tsconfig.json +1 -3
  52. package/package.json +3 -5
  53. package/cli/docs/models.md +0 -58
  54. package/cli/docs/modifiers.md +0 -52
  55. package/cli/docs/plugins.md +0 -70
  56. package/cli/src/checklistPrompt.ts +0 -464
  57. package/cli/src/commands/harnesses.ts +0 -80
  58. package/cli/src/commands/model.ts +0 -68
  59. package/cli/src/commands/models.ts +0 -75
  60. package/cli/src/commands/plugins.ts +0 -35
  61. package/cli/src/commands/skills.ts +0 -40
  62. package/cli/src/commands/status.ts +0 -206
  63. package/cli/src/efforts.ts +0 -89
  64. package/cli/src/engine-native/claudeLsp.ts +0 -301
  65. package/cli/src/engine-native/claudeOptionalPlugins.ts +0 -126
  66. package/cli/src/engine-native/claudePluginPasses.ts +0 -426
  67. package/cli/src/engine-native/claudeRemovals.ts +0 -383
  68. package/cli/src/engine-native/claudeRetired.ts +0 -165
  69. package/cli/src/engine-native/claudeRuntime.ts +0 -157
  70. package/cli/src/engine-native/claudeSettings.ts +0 -201
  71. package/cli/src/engine-native/claudeSettingsModifiers.ts +0 -115
  72. package/cli/src/engine-native/claudeSync.ts +0 -312
  73. package/cli/src/engine-native/codexConfig.ts +0 -214
  74. package/cli/src/engine-native/codexHooks.ts +0 -91
  75. package/cli/src/engine-native/codexPaths.ts +0 -14
  76. package/cli/src/engine-native/codexPlugins.ts +0 -315
  77. package/cli/src/engine-native/codexStatus.ts +0 -25
  78. package/cli/src/engine-native/codexSync.ts +0 -314
  79. package/cli/src/engine-native/codexToml.ts +0 -303
  80. package/cli/src/engine-native/harnesses.ts +0 -138
  81. package/cli/src/engine-native/liveModels.ts +0 -264
  82. package/cli/src/engine-native/models.ts +0 -101
  83. package/cli/src/engine-native/parseModifiers.ts +0 -225
  84. package/cli/src/engine-native/settings.ts +0 -42
  85. package/cli/src/engine-native/skillsInstall.ts +0 -135
  86. package/cli/src/engine-native/skillsLinks.ts +0 -216
  87. package/cli/src/engine-native/skillsManifest.ts +0 -36
  88. package/cli/src/engine-native/skillsPrune.ts +0 -117
  89. package/cli/src/engine-native/skillsRecords.ts +0 -138
  90. package/cli/src/engine-native/skillsSync.ts +0 -57
  91. package/cli/src/engine-native/tomlLines.ts +0 -92
  92. package/cli/src/manifests.ts +0 -145
  93. package/cli/src/terminalCells.ts +0 -191
@@ -1,117 +0,0 @@
1
- /**
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
- *
6
- * The prune deletes only what the kit created: the canonical skill directory
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.
13
- */
14
- import { existsSync, rmSync } from "node:fs";
15
- import { p } from "./exec";
16
- import type { Ctx } from "./index";
17
- import { compareCodepoints } from "./jq";
18
- import { isKitOwnedCopy, lstat, removeKitOwnedCopy, removeLink } from "./skillsLinks";
19
- import { normalizeManifest, skillBase } from "./skillsManifest";
20
- import { directoryIdentity, type SkillRecords } from "./skillsRecords";
21
-
22
- function removeCanonical(path: string): boolean {
23
- try {
24
- rmSync(path, { recursive: true, force: true });
25
- return true;
26
- } catch {
27
- return lstat(path) === undefined;
28
- }
29
- }
30
-
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 {
41
- const { change, echo, warn } = ctx.services.logger;
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
- );
46
- }
47
-
48
- const current = normalizeManifest(manifest);
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
-
61
- let removed = 0;
62
- let failed = 0;
63
- for (const slug of [...records.owned.keys()].sort(compareCodepoints)) {
64
- if (declared(slug)) continue;
65
- const base = skillBase(slug);
66
- const canonical = p(ctx.agentsDir, "skills", base);
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);
70
- const installedCanonical =
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
- }
79
- const claudeEntry = p(ctx.home, ".claude", "skills", base);
80
- const managedClaudeEntry =
81
- lstat(claudeEntry)?.isSymbolicLink() === true || isKitOwnedCopy(claudeEntry);
82
- if (ctx.dryRun) {
83
- echo(`[dry-run] kit-managed skill no longer in SoT — would remove: ${base}`);
84
- if (managedClaudeEntry) {
85
- echo(`[dry-run] kit-managed Claude skill entry — would remove: ~/.claude/skills/${base}`);
86
- }
87
- continue;
88
- }
89
- if (installedCanonical && !removeCanonical(canonical)) {
90
- warn(`Failed to remove kit-managed skill: ${base}`);
91
- failed++;
92
- continue;
93
- }
94
- if (managedClaudeEntry) {
95
- const entryStat = lstat(claudeEntry);
96
- const removedClaudeEntry =
97
- entryStat === undefined ||
98
- (entryStat.isSymbolicLink() ? removeLink(claudeEntry) : removeKitOwnedCopy(claudeEntry));
99
- if (!removedClaudeEntry) {
100
- warn(`Failed to remove kit-managed Claude skill entry: ${base}`);
101
- failed++;
102
- continue;
103
- }
104
- }
105
- records.owned.delete(slug);
106
- removed++;
107
- }
108
-
109
- if (removed > 0) {
110
- change(`Kit-managed skills removed (-${removed})`);
111
- ctx.nextStepTriggers.skillsRestart = true;
112
- }
113
- if (failed > 0)
114
- warn(
115
- `${failed} skill remove(s) failed — re-run with --prune, or delete ~/.agents/skills/<name> and the ~/.claude/skills/<name> link manually`,
116
- );
117
- }
@@ -1,138 +0,0 @@
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,57 +0,0 @@
1
- /**
2
- * EngineNative `sync agents` pipeline: universal-skill bootstrap
3
- * (`npx skills@<pin> add`), Claude symlink healing, --prune reconcile against
4
- * the kit-owned record, and the record writes.
5
- *
6
- * Split: manifest parsing lives in `skillsManifest.ts`, link mechanics and
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
- */
12
- import { mkdirSync } from "node:fs";
13
- import { payloadText } from "../payload";
14
- import { p } from "./exec";
15
- import type { Ctx } from "./index";
16
- import { syncUniversal, type SkillsState } from "./skillsInstall";
17
- import { reconcileRemovals } from "./skillsPrune";
18
- import { readSkillRecords, settlePendingSlug, writeSkillRecords } from "./skillsRecords";
19
-
20
- export type { SkillsState } from "./skillsInstall";
21
- export { COPY_MARKER, linkOrCopy, type LinkOutcome } from "./skillsLinks";
22
- export { normalizeManifest } from "./skillsManifest";
23
-
24
- export async function skillsSync(ctx: Ctx): Promise<SkillsState> {
25
- const state: SkillsState = { present: 0 };
26
- const skillsDir = p(ctx.agentsDir, "skills");
27
- const manifest = payloadText("SoT/.agents/skills.txt");
28
- const records = readSkillRecords(ctx.agentsDir);
29
-
30
- if (!ctx.dryRun) mkdirSync(skillsDir, { recursive: true });
31
-
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);
40
- return state;
41
- }
42
-
43
- // -------------------------------------------------------------- summary ----
44
-
45
- export function skillsSummary(ctx: Ctx, state: SkillsState): void {
46
- const { echo } = ctx.services.logger;
47
- echo(`Skills: ${p(ctx.agentsDir, "skills")}`);
48
- if (!ctx.dryRun) {
49
- echo(` ${state.present} universal skill(s) installed`);
50
- }
51
- }
52
-
53
- export function skillsNextSteps(ctx: Ctx): Array<string> {
54
- return ctx.verbose || ctx.nextStepTriggers.skillsRestart
55
- ? ["Restart Claude Code (and Codex) to discover newly installed universal skills."]
56
- : [];
57
- }
@@ -1,92 +0,0 @@
1
- /**
2
- * The line grammar of the line-based TOML passes: table header lines, key
3
- * lines, and the lines that continue a value from an earlier line. The module
4
- * imports nothing, so `manifests.ts` can read a Codex config without a runtime
5
- * cycle through `codexToml.ts` and `efforts.ts`.
6
- */
7
-
8
- export function isTomlHeaderLine(line: string): boolean {
9
- return /^[ \t]*\[/.test(line);
10
- }
11
-
12
- /** Offset just past the quoted string that starts at `start`, or the line end when it stays open. */
13
- function skipQuoted(line: string, start: number): number {
14
- const quote = line[start];
15
- let offset = start + 1;
16
- while (offset < line.length) {
17
- if (quote === '"' && line[offset] === "\\") {
18
- offset += 2;
19
- continue;
20
- }
21
- if (line[offset] === quote) return offset + 1;
22
- offset++;
23
- }
24
- return offset;
25
- }
26
-
27
- /** Offset of the `=` that ends the key on a key line, or undefined for other lines. */
28
- export function keyValueSeparator(line: string): number | undefined {
29
- if (/^[ \t]*($|#|\[)/.test(line)) return undefined;
30
- let offset = 0;
31
- while (offset < line.length) {
32
- const char = line[offset]!;
33
- if (char === "=") return offset;
34
- offset = char === '"' || char === "'" ? skipQuoted(line, offset) : offset + 1;
35
- }
36
- return undefined;
37
- }
38
-
39
- /**
40
- * Mark each line that continues a value opened on an earlier line: the body of
41
- * a `"""` or `'''` string, or the rest of an array or inline table that spans
42
- * lines. A marked line is never a table header or a key line.
43
- */
44
- export function tomlContinuationLines(lines: ReadonlyArray<string>): Array<boolean> {
45
- const continuation: Array<boolean> = [];
46
- let openString: string | undefined;
47
- let depth = 0;
48
- const scanValue = (line: string, start: number): void => {
49
- let offset = start;
50
- while (offset < line.length) {
51
- if (openString !== undefined) {
52
- if (openString === '"""' && line[offset] === "\\") {
53
- offset += 2;
54
- } else if (line.startsWith(openString, offset)) {
55
- // A closing delimiter can carry up to two extra quotes of string content.
56
- let end = offset + 3;
57
- while (end < offset + 5 && line[end] === openString[0]) end++;
58
- offset = end;
59
- openString = undefined;
60
- } else {
61
- offset++;
62
- }
63
- continue;
64
- }
65
- const char = line[offset]!;
66
- if (char === "#") return;
67
- if (line.startsWith('"""', offset) || line.startsWith("'''", offset)) {
68
- openString = line.slice(offset, offset + 3);
69
- offset += 3;
70
- continue;
71
- }
72
- if (char === '"' || char === "'") {
73
- offset = skipQuoted(line, offset);
74
- continue;
75
- }
76
- if (char === "[" || char === "{") depth++;
77
- else if ((char === "]" || char === "}") && depth > 0) depth--;
78
- offset++;
79
- }
80
- };
81
- for (const line of lines) {
82
- if (openString !== undefined || depth > 0) {
83
- continuation.push(true);
84
- scanValue(line, 0);
85
- continue;
86
- }
87
- continuation.push(false);
88
- const separator = keyValueSeparator(line);
89
- if (separator !== undefined) scanValue(line, separator + 1);
90
- }
91
- return continuation;
92
- }
@@ -1,145 +0,0 @@
1
- import { existsSync, lstatSync, readFileSync, readdirSync, readlinkSync } from "node:fs";
2
- import { dirname, join, resolve } from "node:path";
3
- import { pluginUserScopeInstalled } from "./engine-native/claudePluginPasses";
4
- import { codexHome } from "./engine-native/codexPaths";
5
- import { engineHome } from "./engine-native/harnesses";
6
- import { isObject, readJsonFile } from "./engine-native/jq";
7
- import type { JsonObject } from "./engine-native/sharedTypes";
8
- import { skillBase } from "./engine-native/skillsManifest";
9
- import { COPY_MARKER } from "./engine-native/skillsSync";
10
- import {
11
- isTomlHeaderLine,
12
- keyValueSeparator,
13
- tomlContinuationLines,
14
- } from "./engine-native/tomlLines";
15
- import { payloadText } from "./payload";
16
-
17
- export type Tool = "claude" | "codex";
18
-
19
- const readJson = (path: string): any => JSON.parse(readFileSync(path, "utf8"));
20
- const readJsonText = (text: string): any => JSON.parse(text);
21
-
22
- /** SoT settings (claude) — model/effort/env for drift display. */
23
- export const sotClaudeSettings = (): any => readJsonText(payloadText("SoT/.claude/settings.json"));
24
-
25
- export const deployedClaudeSettings = (): any | undefined => {
26
- const p = join(engineHome(), ".claude", "settings.json");
27
- return existsSync(p) ? readJson(p) : undefined;
28
- };
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
- */
40
- export function topLevelTomlString(text: string, setting: string): string | undefined {
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];
50
- }
51
- return undefined;
52
- }
53
-
54
- const tomlModel = (path: string): string | undefined => {
55
- if (!existsSync(path)) return undefined;
56
- return topLevelTomlString(readFileSync(path, "utf8"), "model");
57
- };
58
-
59
- export const sotCodexModel = (): string | undefined =>
60
- topLevelTomlString(payloadText("SoT/.codex/config.toml"), "model");
61
-
62
- export const deployedCodexModel = (): string | undefined =>
63
- tomlModel(join(codexHome(engineHome()), "config.toml"));
64
-
65
- const installedPluginsPath = (): string =>
66
- join(engineHome(), ".claude", "plugins", "installed_plugins.json");
67
-
68
- /** Read the user-scope plugin records; a missing or malformed file yields `undefined`. */
69
- const readInstalledPlugins = (path: string): JsonObject | undefined => {
70
- const doc = readJsonFile(path);
71
- if (doc === undefined || !isObject(doc)) return undefined;
72
- const plugins = doc["plugins"];
73
- return plugins !== undefined && isObject(plugins) ? plugins : undefined;
74
- };
75
-
76
- /** State of ~/.claude/plugins/installed_plugins.json: missing, an object with object `plugins`, or not. */
77
- export const installedPluginsState = (): "absent" | "valid" | "malformed" => {
78
- const path = installedPluginsPath();
79
- if (!existsSync(path)) return "absent";
80
- return readInstalledPlugins(path) === undefined ? "malformed" : "valid";
81
- };
82
-
83
- /** Installed plugins (user scope) vs SoT enabledPlugins tri-state. */
84
- export const pluginsView = (): Array<{
85
- plugin: string;
86
- sot: "true" | "false" | "absent";
87
- installed: boolean;
88
- }> => {
89
- const sot: Record<string, boolean> = sotClaudeSettings().enabledPlugins ?? {};
90
- const installedPath = installedPluginsPath();
91
- const installed: Record<string, unknown> = readInstalledPlugins(installedPath) ?? {};
92
- const names = new Set([...Object.keys(sot), ...Object.keys(installed)]);
93
- return [...names].sort().map((plugin) => ({
94
- plugin,
95
- sot: plugin in sot ? (sot[plugin] ? "true" : "false") : "absent",
96
- installed: pluginUserScopeInstalled(installedPath, plugin),
97
- }));
98
- };
99
-
100
- /** Universal skills: SoT manifest slugs vs ~/.agents/skills contents. */
101
- export const skillsView = (): Array<{
102
- skill: string;
103
- declared: boolean;
104
- installed: boolean;
105
- /** Claude entry resolves to the canonical skill by symlink, junction, or kit-created copy. */
106
- claudeSymlink: boolean;
107
- }> => {
108
- const declared = payloadText("SoT/.agents/skills.txt")
109
- .split("\n")
110
- .map((l) => l.replace(/#.*$/, "").trim())
111
- .filter((l) => l.length > 0)
112
- .map(skillBase);
113
- const home = engineHome();
114
- const skillsDir = join(home, ".agents", "skills");
115
- const installed = existsSync(skillsDir)
116
- ? readdirSync(skillsDir, { withFileTypes: true })
117
- .filter((e) => e.isDirectory())
118
- .map((e) => e.name)
119
- : [];
120
- const names = new Set([...declared, ...installed]);
121
- return [...names].sort().map((skill) => {
122
- const link = join(home, ".claude", "skills", skill);
123
- const canonical = resolve(skillsDir, skill);
124
- let claudeSymlink = false;
125
- try {
126
- const target = resolve(dirname(link), readlinkSync(link));
127
- claudeSymlink = target === canonical && existsSync(target);
128
- } catch {
129
- /* not a symlink or missing */
130
- }
131
- if (!claudeSymlink && installed.includes(skill)) {
132
- try {
133
- claudeSymlink = lstatSync(link).isDirectory() && existsSync(join(link, COPY_MARKER));
134
- } catch {
135
- /* missing Claude entry */
136
- }
137
- }
138
- return {
139
- skill,
140
- declared: declared.includes(skill),
141
- installed: installed.includes(skill),
142
- claudeSymlink,
143
- };
144
- });
145
- };