docks-kit 0.20.10 → 0.21.1
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 +14 -7
- package/README.md +19 -10
- package/cli/docs/command-guards.md +30 -12
- package/cli/docs/flags.md +34 -5
- package/cli/docs/omp-models.md +96 -44
- package/cli/src/argv.ts +4 -0
- package/cli/src/commands/omp.ts +95 -23
- package/cli/src/commands/scratch.ts +75 -0
- package/cli/src/commands/tidy.ts +91 -0
- package/cli/src/engine-native/ompKitPlugin.ts +94 -0
- package/cli/src/engine-native/ompOverlay.ts +96 -26
- package/cli/src/engine-native/ompPlugins.ts +41 -8
- package/cli/src/engine-native/ompSync.ts +7 -4
- package/cli/src/engine-native/scratch.ts +188 -0
- package/cli/src/engine-native/tidy.ts +1296 -0
- package/cli/src/engine-native/tidyLock.ts +163 -0
- package/cli/src/engine-native/tidyReport.ts +509 -0
- package/cli/src/generated/sotPayload.ts +14 -6
- package/cli/src/main.ts +8 -0
- package/cli/tsconfig.json +1 -1
- package/docks-kit +2 -2
- package/docks-kit.ps1 +2 -2
- package/package.json +3 -3
|
@@ -1,21 +1,31 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* EngineNative omp plugin pass: marketplace-plugin install/upgrade
|
|
3
|
-
* pinned pi-intercom npm plugin
|
|
4
|
-
*
|
|
2
|
+
* EngineNative omp plugin pass: marketplace-plugin install/upgrade, the
|
|
3
|
+
* pinned pi-intercom npm plugin, and the link of the kit plugin that
|
|
4
|
+
* `ompKitPlugin.ts syncKitPlugin` writes. Split from ompSync.ts; the
|
|
5
|
+
* orchestration still lives there.
|
|
5
6
|
*/
|
|
7
|
+
import { realpathSync } from "node:fs";
|
|
8
|
+
|
|
6
9
|
import { processFailureSummary, spawnProcess } from "./exec";
|
|
7
10
|
import { recordFailure } from "./failures";
|
|
8
11
|
import type { Ctx } from "./index";
|
|
9
12
|
import { isObject, parseJson } from "./jq";
|
|
13
|
+
import { KIT_PLUGIN_NAME, kitPluginDir } from "./ompKitPlugin";
|
|
10
14
|
import { field } from "./toolchain";
|
|
11
15
|
|
|
12
16
|
const MARKETPLACE_PLUGIN_IDS = ["docks@docks", "plan-lifecycle@docks"] as const;
|
|
13
17
|
|
|
14
18
|
// -------------------------------------------------------------- plugins ----
|
|
15
19
|
|
|
20
|
+
interface InstalledNpmPlugin {
|
|
21
|
+
readonly version: string;
|
|
22
|
+
/** The `node_modules` entry of the plugin, a symbolic link for a linked plugin. */
|
|
23
|
+
readonly path: string | undefined;
|
|
24
|
+
}
|
|
25
|
+
|
|
16
26
|
interface InstalledPlugins {
|
|
17
27
|
readonly marketplace: Set<string>;
|
|
18
|
-
readonly npm: Map<string,
|
|
28
|
+
readonly npm: Map<string, InstalledNpmPlugin>;
|
|
19
29
|
}
|
|
20
30
|
|
|
21
31
|
async function installedPluginIdsFromCli(): Promise<InstalledPlugins | undefined> {
|
|
@@ -46,11 +56,12 @@ async function installedPluginIdsFromCli(): Promise<InstalledPlugins | undefined
|
|
|
46
56
|
marketplace.add(row["id"]);
|
|
47
57
|
}
|
|
48
58
|
|
|
49
|
-
const npm = new Map<string,
|
|
59
|
+
const npm = new Map<string, InstalledNpmPlugin>();
|
|
50
60
|
for (const row of value["npm"]) {
|
|
51
61
|
if (!isObject(row) || typeof row["name"] !== "string" || typeof row["version"] !== "string")
|
|
52
62
|
continue;
|
|
53
|
-
|
|
63
|
+
const path = typeof row["path"] === "string" ? row["path"] : undefined;
|
|
64
|
+
npm.set(row["name"], { version: row["version"], path });
|
|
54
65
|
}
|
|
55
66
|
return { marketplace, npm };
|
|
56
67
|
}
|
|
@@ -73,6 +84,14 @@ async function runPluginCommand(
|
|
|
73
84
|
return false;
|
|
74
85
|
}
|
|
75
86
|
|
|
87
|
+
function realPath(path: string): string | undefined {
|
|
88
|
+
try {
|
|
89
|
+
return realpathSync(path);
|
|
90
|
+
} catch {
|
|
91
|
+
return undefined;
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
|
|
76
95
|
export async function syncPlugins(ctx: Ctx): Promise<number> {
|
|
77
96
|
const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger;
|
|
78
97
|
|
|
@@ -105,6 +124,7 @@ export async function syncPlugins(ctx: Ctx): Promise<number> {
|
|
|
105
124
|
} else {
|
|
106
125
|
echo(`[dry-run] omp install pi-intercom@${piIntercomPin}`);
|
|
107
126
|
}
|
|
127
|
+
echo(`[dry-run] omp plugin link ${kitPluginDir(ctx.home)}`);
|
|
108
128
|
return 0;
|
|
109
129
|
}
|
|
110
130
|
|
|
@@ -121,7 +141,8 @@ export async function syncPlugins(ctx: Ctx): Promise<number> {
|
|
|
121
141
|
installed === undefined
|
|
122
142
|
? 0
|
|
123
143
|
: MARKETPLACE_PLUGIN_IDS.filter((pluginId) => installed.marketplace.has(pluginId)).length +
|
|
124
|
-
(piIntercomPin !== "" && installed.npm.has("pi-intercom") ? 1 : 0)
|
|
144
|
+
(piIntercomPin !== "" && installed.npm.has("pi-intercom") ? 1 : 0) +
|
|
145
|
+
(installed.npm.has(KIT_PLUGIN_NAME) ? 1 : 0);
|
|
125
146
|
let operationsSucceeded = 0;
|
|
126
147
|
|
|
127
148
|
for (const pluginId of MARKETPLACE_PLUGIN_IDS) {
|
|
@@ -143,7 +164,7 @@ export async function syncPlugins(ctx: Ctx): Promise<number> {
|
|
|
143
164
|
if (piIntercomPin === "") {
|
|
144
165
|
warn("pi-intercom install skipped because SoT/toolchain.json has no verified pi-intercom pin");
|
|
145
166
|
} else {
|
|
146
|
-
const installedVersion = installed?.npm.get("pi-intercom");
|
|
167
|
+
const installedVersion = installed?.npm.get("pi-intercom")?.version;
|
|
147
168
|
const present = installedVersion !== undefined;
|
|
148
169
|
if (installedVersion === piIntercomPin) {
|
|
149
170
|
verbose(`omp npm plugin pi-intercom already installed at ${piIntercomPin}`);
|
|
@@ -160,6 +181,18 @@ export async function syncPlugins(ctx: Ctx): Promise<number> {
|
|
|
160
181
|
}
|
|
161
182
|
}
|
|
162
183
|
|
|
184
|
+
// The kit plugin is linked when omp's entry resolves to the kit directory.
|
|
185
|
+
// A refresh never applies: the link always points at the current files.
|
|
186
|
+
const kitDir = kitPluginDir(ctx.home);
|
|
187
|
+
const kitPluginPath = installed?.npm.get(KIT_PLUGIN_NAME)?.path;
|
|
188
|
+
const linkedTarget = kitPluginPath === undefined ? undefined : realPath(kitPluginPath);
|
|
189
|
+
if (linkedTarget !== undefined && linkedTarget === realPath(kitDir)) {
|
|
190
|
+
verbose(`omp kit plugin ${KIT_PLUGIN_NAME} already linked`);
|
|
191
|
+
} else if (await runPluginCommand(ctx, KIT_PLUGIN_NAME, ["plugin", "link", kitDir])) {
|
|
192
|
+
operationsSucceeded++;
|
|
193
|
+
if (installed?.npm.has(KIT_PLUGIN_NAME) !== true) pluginsInstalled++;
|
|
194
|
+
}
|
|
195
|
+
|
|
163
196
|
if (operationsSucceeded > 0) {
|
|
164
197
|
change(`omp plugins synced (plugins: ~${operationsSucceeded})`);
|
|
165
198
|
ctx.nextStepTriggers.ompRestart = true;
|
|
@@ -6,10 +6,10 @@
|
|
|
6
6
|
* Resolution stays within the environment and filesystem probes so no omp
|
|
7
7
|
* subcommand runs under ctx.dryRun.
|
|
8
8
|
*
|
|
9
|
-
* Split: file deploy lives in `ompFileDeploy.ts`, the
|
|
10
|
-
* `
|
|
11
|
-
*
|
|
12
|
-
* summary surface.
|
|
9
|
+
* Split: file deploy lives in `ompFileDeploy.ts`, the kit plugin files in
|
|
10
|
+
* `ompKitPlugin.ts`, the marketplace pass in `ompMarketplace.ts`, the plugin
|
|
11
|
+
* pass in `ompPlugins.ts`, and the retired-key prune in `ompRemovals.ts`.
|
|
12
|
+
* This module keeps the orchestration plus the summary surface.
|
|
13
13
|
*/
|
|
14
14
|
import { isAbsolute, resolve } from "node:path";
|
|
15
15
|
|
|
@@ -19,6 +19,7 @@ import type { Ctx } from "./index";
|
|
|
19
19
|
import { ompPaths } from "./ompPaths";
|
|
20
20
|
import { mergeOmpConfig, mergeOmpModels } from "./ompYaml";
|
|
21
21
|
import { ensureDirectory, syncMergedYaml, syncWholeFile } from "./ompFileDeploy";
|
|
22
|
+
import { syncKitPlugin } from "./ompKitPlugin";
|
|
22
23
|
import { syncMarketplace } from "./ompMarketplace";
|
|
23
24
|
import { syncPlugins } from "./ompPlugins";
|
|
24
25
|
import { syncOmpModelRemovals, syncOmpRemovals } from "./ompRemovals";
|
|
@@ -79,6 +80,8 @@ export async function ompSync(ctx: Ctx): Promise<OmpState> {
|
|
|
79
80
|
"omp intercom configuration already in sync",
|
|
80
81
|
"omp intercom configuration synced",
|
|
81
82
|
);
|
|
83
|
+
// The plugin pass links this directory, so the files must exist first.
|
|
84
|
+
syncKitPlugin(ctx);
|
|
82
85
|
|
|
83
86
|
const legacyRegistryFile =
|
|
84
87
|
paths.dataRoot === paths.configRoot ? undefined : p(paths.configRoot, "marketplaces.json");
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Agent temporary directories. `createScratchDir` makes a private directory
|
|
3
|
+
* under the kit scratch root. `removeTemporaryPath` removes a path only when it
|
|
4
|
+
* is strictly inside an allowed root and no other user can change a directory
|
|
5
|
+
* on its path, so a deny-listed `rm -r` is never needed for cleanup and the
|
|
6
|
+
* home directory and `/` can never be the target.
|
|
7
|
+
*/
|
|
8
|
+
import {
|
|
9
|
+
chmodSync,
|
|
10
|
+
lstatSync,
|
|
11
|
+
mkdirSync,
|
|
12
|
+
mkdtempSync,
|
|
13
|
+
realpathSync,
|
|
14
|
+
rmSync,
|
|
15
|
+
statSync,
|
|
16
|
+
} from "node:fs";
|
|
17
|
+
import { dirname, isAbsolute, join, relative } from "node:path";
|
|
18
|
+
|
|
19
|
+
import { p } from "./exec";
|
|
20
|
+
|
|
21
|
+
const LABEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
|
|
22
|
+
|
|
23
|
+
export function kitCacheDir(home: string): string {
|
|
24
|
+
return p(home, ".cache", "docks-kit");
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export function scratchRoot(home: string): string {
|
|
28
|
+
return p(kitCacheDir(home), "scratch");
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export function createScratchDir(root: string, label: string): string {
|
|
32
|
+
if (!LABEL_PATTERN.test(label)) {
|
|
33
|
+
throw new Error("label must match ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$");
|
|
34
|
+
}
|
|
35
|
+
mkdirSync(root, { recursive: true, mode: 0o700 });
|
|
36
|
+
chmodSync(root, 0o700);
|
|
37
|
+
const directory = mkdtempSync(join(root, `${label}-`));
|
|
38
|
+
chmodSync(directory, 0o700);
|
|
39
|
+
return realpathSync(directory);
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** True when `child` is `parent` itself or lies below it. */
|
|
43
|
+
export function isSameOrInside(parent: string, child: string): boolean {
|
|
44
|
+
const path = relative(parent, child);
|
|
45
|
+
return path === "" || (!path.startsWith("..") && !isAbsolute(path));
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** True when `child` lies strictly below `parent`. */
|
|
49
|
+
export function isStrictlyInside(parent: string, child: string): boolean {
|
|
50
|
+
const path = relative(parent, child);
|
|
51
|
+
return path !== "" && !path.startsWith("..") && !isAbsolute(path);
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
function realpathOrUndefined(path: string): string | undefined {
|
|
55
|
+
try {
|
|
56
|
+
return realpathSync(path);
|
|
57
|
+
} catch {
|
|
58
|
+
return undefined;
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
const STICKY = 0o1000;
|
|
63
|
+
const GROUP_OR_OTHER_WRITE = 0o022;
|
|
64
|
+
|
|
65
|
+
/** The user and root may own a directory on a trusted path. */
|
|
66
|
+
function isTrustedOwner(uid: number, user: number): boolean {
|
|
67
|
+
return uid === user || uid === 0;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* The first directory from the filesystem root down to the parent of `path`
|
|
72
|
+
* that another user can change, or `undefined`. The user or root must own each
|
|
73
|
+
* directory, and group and others must not write it, except a sticky directory
|
|
74
|
+
* whose next entry on the path the user or root owns: POSIX lets only that
|
|
75
|
+
* entry's owner, the directory owner, or root rename such an entry.
|
|
76
|
+
*/
|
|
77
|
+
function untrustedParent(path: string, user: number): string | undefined {
|
|
78
|
+
const chain = [path];
|
|
79
|
+
for (let parent = dirname(path); parent !== chain[0]; parent = dirname(parent)) {
|
|
80
|
+
chain.unshift(parent);
|
|
81
|
+
}
|
|
82
|
+
for (let index = 0; index < chain.length - 1; index++) {
|
|
83
|
+
const directory = lstatSync(chain[index]);
|
|
84
|
+
if (!directory.isDirectory() || !isTrustedOwner(directory.uid, user)) return chain[index];
|
|
85
|
+
if ((directory.mode & GROUP_OR_OTHER_WRITE) === 0) continue;
|
|
86
|
+
const sticky = (directory.mode & STICKY) !== 0;
|
|
87
|
+
if (!sticky || !isTrustedOwner(lstatSync(chain[index + 1]).uid, user)) return chain[index];
|
|
88
|
+
}
|
|
89
|
+
return undefined;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* True when no other user can replace or change `root`: its path is trusted,
|
|
94
|
+
* the user or root owns it, and others cannot write it unless it is sticky.
|
|
95
|
+
* Windows has no POSIX owner bits, so every root passes there.
|
|
96
|
+
*/
|
|
97
|
+
function isTrustedRoot(root: string): boolean {
|
|
98
|
+
if (process.getuid === undefined) return true;
|
|
99
|
+
const user = process.getuid();
|
|
100
|
+
const stats = lstatSync(root);
|
|
101
|
+
if (!isTrustedOwner(stats.uid, user)) return false;
|
|
102
|
+
if ((stats.mode & GROUP_OR_OTHER_WRITE) !== 0 && (stats.mode & STICKY) === 0) return false;
|
|
103
|
+
return untrustedParent(root, user) === undefined;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
export function allowedRemovalRoots(input: {
|
|
107
|
+
readonly home: string;
|
|
108
|
+
readonly scratch: string;
|
|
109
|
+
readonly tmp: string;
|
|
110
|
+
readonly platform: NodeJS.Platform;
|
|
111
|
+
}): ReadonlyArray<string> {
|
|
112
|
+
const candidates = [input.scratch, input.tmp];
|
|
113
|
+
if (input.platform !== "win32") candidates.push("/tmp", "/var/tmp");
|
|
114
|
+
const home = realpathOrUndefined(input.home) ?? input.home;
|
|
115
|
+
const roots: Array<string> = [];
|
|
116
|
+
for (const candidate of candidates) {
|
|
117
|
+
const root = realpathOrUndefined(candidate);
|
|
118
|
+
if (root === undefined || roots.includes(root)) continue;
|
|
119
|
+
if (dirname(root) === root || isSameOrInside(root, home)) continue;
|
|
120
|
+
if (!isTrustedRoot(root)) continue;
|
|
121
|
+
roots.push(root);
|
|
122
|
+
}
|
|
123
|
+
return roots;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
export type RemovalOutcome =
|
|
127
|
+
| { readonly kind: "removed"; readonly path: string }
|
|
128
|
+
| { readonly kind: "refused"; readonly path: string; readonly reason: string };
|
|
129
|
+
|
|
130
|
+
function errorCode(cause: unknown): string | undefined {
|
|
131
|
+
return cause instanceof Error && "code" in cause && typeof cause.code === "string"
|
|
132
|
+
? cause.code
|
|
133
|
+
: undefined;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
function errorMessage(cause: unknown): string {
|
|
137
|
+
return cause instanceof Error ? cause.message : String(cause);
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/**
|
|
141
|
+
* Remove `operand` when every check passes, in this order: it exists, it is
|
|
142
|
+
* not a symbolic link (also with trailing separators), its real path is
|
|
143
|
+
* strictly inside one root and is no root itself, it does not contain the home
|
|
144
|
+
* directory, the current user owns it, no other user can change a directory on
|
|
145
|
+
* its path, and it is on the same filesystem as its root. The first failed
|
|
146
|
+
* check refuses and deletes nothing.
|
|
147
|
+
*/
|
|
148
|
+
export function removeTemporaryPath(
|
|
149
|
+
operand: string,
|
|
150
|
+
roots: ReadonlyArray<string>,
|
|
151
|
+
home: string,
|
|
152
|
+
): RemovalOutcome {
|
|
153
|
+
const refuse = (reason: string): RemovalOutcome => ({ kind: "refused", path: operand, reason });
|
|
154
|
+
// `lstat` of `link/` follows the link, so check the entry without trailing separators.
|
|
155
|
+
const trailing = process.platform === "win32" ? /[\\/]+$/ : /\/+$/;
|
|
156
|
+
const entry = operand.replace(trailing, "") || operand;
|
|
157
|
+
try {
|
|
158
|
+
if (lstatSync(entry).isSymbolicLink()) return refuse("is a symbolic link");
|
|
159
|
+
} catch (cause) {
|
|
160
|
+
return errorCode(cause) === "ENOENT" ? refuse("does not exist") : refuse(errorMessage(cause));
|
|
161
|
+
}
|
|
162
|
+
try {
|
|
163
|
+
const target = realpathSync(entry);
|
|
164
|
+
const root = roots.includes(target)
|
|
165
|
+
? undefined
|
|
166
|
+
: roots.find((candidate) => isStrictlyInside(candidate, target));
|
|
167
|
+
if (root === undefined) {
|
|
168
|
+
return refuse("is outside the scratch root, the system temporary directory, and /var/tmp");
|
|
169
|
+
}
|
|
170
|
+
if (isSameOrInside(target, realpathOrUndefined(home) ?? home)) {
|
|
171
|
+
return refuse("contains the home directory");
|
|
172
|
+
}
|
|
173
|
+
const stats = statSync(target);
|
|
174
|
+
if (process.getuid !== undefined) {
|
|
175
|
+
const user = process.getuid();
|
|
176
|
+
if (stats.uid !== user) return refuse("is owned by another user");
|
|
177
|
+
const parent = untrustedParent(target, user);
|
|
178
|
+
if (parent !== undefined) {
|
|
179
|
+
return refuse(`has a parent directory that another user can change: ${parent}`);
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
if (stats.dev !== statSync(root).dev) return refuse("is on another filesystem");
|
|
183
|
+
rmSync(target, { recursive: true, force: false });
|
|
184
|
+
return { kind: "removed", path: target };
|
|
185
|
+
} catch (cause) {
|
|
186
|
+
return refuse(errorMessage(cause));
|
|
187
|
+
}
|
|
188
|
+
}
|