docks-kit 0.25.0 → 0.27.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +12 -10
- package/README.md +40 -30
- package/cli/dist/docks-kit.js +24701 -0
- package/cli/docs/command-guards.md +8 -5
- package/cli/docs/install.md +41 -32
- package/cli/docs/omp-context.md +1 -1
- package/cli/docs/omp-models.md +1 -1
- package/cli/docs/overview.md +3 -3
- package/cli/docs/platforms.md +8 -8
- package/cli/src/agentDocs/agentFirstCheck.ts +786 -0
- package/cli/src/agentDocs/bridgeCheck.ts +226 -0
- package/cli/src/agentDocs/commands.ts +63 -0
- package/cli/src/agentDocs/prTemplate.ts +211 -0
- package/cli/src/agentDocs/services.ts +202 -0
- package/cli/src/agentDocs/shared.ts +730 -0
- package/cli/src/agentDocs/verifySkill.ts +136 -0
- package/cli/src/argv.ts +25 -1
- package/cli/src/commands/agentDocs.ts +29 -0
- package/cli/src/commands/plan.ts +29 -0
- package/cli/src/commands/skill.ts +29 -0
- package/cli/src/commands/update.ts +90 -66
- package/cli/src/engine-native/DESIGN.md +10 -9
- package/cli/src/engine-native/os/targets.ts +6 -19
- package/cli/src/engine.ts +0 -6
- package/cli/src/generated/sotPayload.ts +51 -79
- package/cli/src/kitHome.ts +7 -10
- package/cli/src/main.ts +12 -4
- package/cli/src/plan/bytes.ts +110 -0
- package/cli/src/plan/checkout.ts +379 -0
- package/cli/src/plan/commands.ts +1192 -0
- package/cli/src/plan/github.ts +816 -0
- package/cli/src/plan/records.ts +623 -0
- package/cli/src/plan/repository.ts +53 -0
- package/cli/src/plan/reviews.ts +292 -0
- package/cli/src/plan/services.ts +256 -0
- package/cli/src/plan/types.ts +164 -0
- package/cli/src/skills/commands.ts +142 -0
- package/cli/src/skills/config.json +30 -0
- package/cli/src/skills/files.ts +74 -0
- package/cli/src/skills/frontmatter.ts +148 -0
- package/cli/src/skills/guard.ts +366 -0
- package/cli/src/skills/kitGate.ts +406 -0
- package/cli/src/skills/rubric.ts +143 -0
- package/docks-kit +9 -40
- package/docks-kit.ps1 +10 -61
- package/package.json +10 -8
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `docks-kit agent-docs verify-skill detect | write-gate <path>... | entry-gate`: check the project `verify` skill and
|
|
3
|
+
* guard each write that creates it. The skill lives at `.agents/skills/verify/SKILL.md`. The steps and the meaning of
|
|
4
|
+
* each line live in the plan-workspace reference `verify-skill-template.md`. Run it from the repository root.
|
|
5
|
+
*
|
|
6
|
+
* Output lines:
|
|
7
|
+
* detect `verify skill: present` or `verify skill: missing`; one `verify unverified: <n>:<line>` line for
|
|
8
|
+
* each line of the skill that holds `not observed:`; `ERROR verify skill check failed: cannot read
|
|
9
|
+
* <file>` when the skill cannot be read.
|
|
10
|
+
* write-gate one `target occupied: <path> ...` line for each path that must not be written: a symlink, a path
|
|
11
|
+
* that holds a `..` segment, or a path whose nearest existing folder cannot be entered or resolves
|
|
12
|
+
* outside the current folder. Nothing for a writable path.
|
|
13
|
+
* entry-gate `target occupied: .agents/skills/verify exists` when an entry is there, a dangling symlink included.
|
|
14
|
+
*
|
|
15
|
+
* Exit status: 2 after an ERROR line, 1 for a usage error, otherwise 0. `target occupied` lines do not change the
|
|
16
|
+
* status.
|
|
17
|
+
*/
|
|
18
|
+
import path from "node:path";
|
|
19
|
+
|
|
20
|
+
import { Effect } from "effect";
|
|
21
|
+
|
|
22
|
+
import { UsageError } from "./shared";
|
|
23
|
+
import { AgentDocsFiles, errorDetail, printLines, writeStderr } from "./services";
|
|
24
|
+
|
|
25
|
+
const USAGE = "usage: docks-kit agent-docs verify-skill detect | write-gate <path>... | entry-gate";
|
|
26
|
+
const SKILL_DIR = ".agents/skills/verify";
|
|
27
|
+
const SKILL_FILE = `${SKILL_DIR}/SKILL.md`;
|
|
28
|
+
const UNVERIFIED_MARK = "not observed:";
|
|
29
|
+
|
|
30
|
+
/** The detect lines; on `ok: false`, `lines` still holds every line, the ERROR line included. */
|
|
31
|
+
export interface VerifySkillResult {
|
|
32
|
+
readonly ok: boolean;
|
|
33
|
+
readonly lines: ReadonlyArray<string>;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/** The detect lines for the current folder. On `ok: false`, the cause is on stderr. */
|
|
37
|
+
export const verifySkillLines = Effect.fn("verifySkill.lines")(function* () {
|
|
38
|
+
const files = yield* AgentDocsFiles;
|
|
39
|
+
const lines: Array<string> = [];
|
|
40
|
+
let ok = true;
|
|
41
|
+
if ((yield* files.stat(SKILL_FILE)) === "file") {
|
|
42
|
+
lines.push("verify skill: present");
|
|
43
|
+
const text = yield* files
|
|
44
|
+
.readFile(SKILL_FILE, "utf8")
|
|
45
|
+
.pipe(
|
|
46
|
+
Effect.catchTag("FileError", (error) =>
|
|
47
|
+
writeStderr(
|
|
48
|
+
`verify-skill: cannot read ${SKILL_FILE} (${errorDetail(error)}); make it readable and run detect again\n`,
|
|
49
|
+
).pipe(Effect.as(null)),
|
|
50
|
+
),
|
|
51
|
+
);
|
|
52
|
+
if (text === null) {
|
|
53
|
+
lines.push(`ERROR verify skill check failed: cannot read ${SKILL_FILE}`);
|
|
54
|
+
ok = false;
|
|
55
|
+
} else {
|
|
56
|
+
// `grep -n` numbers lines from 1 and ends the last line at the end of the file.
|
|
57
|
+
text
|
|
58
|
+
.replace(/\n$/u, "")
|
|
59
|
+
.split("\n")
|
|
60
|
+
.forEach((line, index) => {
|
|
61
|
+
if (line.includes(UNVERIFIED_MARK)) lines.push(`verify unverified: ${index + 1}:${line}`);
|
|
62
|
+
});
|
|
63
|
+
}
|
|
64
|
+
} else {
|
|
65
|
+
lines.push("verify skill: missing");
|
|
66
|
+
}
|
|
67
|
+
const result: VerifySkillResult = { ok, lines };
|
|
68
|
+
return result;
|
|
69
|
+
});
|
|
70
|
+
|
|
71
|
+
/** The folder that `cd` would enter for `target`: its nearest existing ancestor folder. */
|
|
72
|
+
const nearestFolder = Effect.fn("verifySkill.nearestFolder")(function* (target: string) {
|
|
73
|
+
const files = yield* AgentDocsFiles;
|
|
74
|
+
let folder = path.dirname(target);
|
|
75
|
+
while ((yield* files.stat(folder)) !== "directory") {
|
|
76
|
+
const parent = path.dirname(folder);
|
|
77
|
+
if (parent === folder) break;
|
|
78
|
+
folder = parent;
|
|
79
|
+
}
|
|
80
|
+
return folder;
|
|
81
|
+
});
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* The refusal for one path that a step wants to write, or null when the write may go on. A write must never go
|
|
85
|
+
* through a symlink or land outside the repository.
|
|
86
|
+
*/
|
|
87
|
+
const refusal = Effect.fn("verifySkill.refusal")(function* (root: string, target: string) {
|
|
88
|
+
const files = yield* AgentDocsFiles;
|
|
89
|
+
if (yield* files.isSymlink(target)) return `target occupied: ${target} is a symlink`;
|
|
90
|
+
// The kernel resolves `link/..` to the parent of the link target, while path.dirname and the nearest-folder search
|
|
91
|
+
// remove `..` as text. No path with `..` passes, so both agree.
|
|
92
|
+
if (target.split("/").includes("..")) return `target occupied: ${target} holds a .. segment`;
|
|
93
|
+
const folder = yield* nearestFolder(target);
|
|
94
|
+
// `cd` needs search permission on the folder; realpath alone does not check it. The native realpath resolves each
|
|
95
|
+
// part as the kernel does; the JavaScript one removes `..` as text before it follows a symlink.
|
|
96
|
+
const resolved = yield* files.canSearch(folder).pipe(
|
|
97
|
+
Effect.andThen(files.realPathNative(folder)),
|
|
98
|
+
Effect.catchTag("FileError", () => Effect.succeed(null)),
|
|
99
|
+
);
|
|
100
|
+
if (resolved === null) return `target occupied: cannot resolve the folder of ${target}`;
|
|
101
|
+
if (!`${resolved}/`.startsWith(`${root}/`))
|
|
102
|
+
return `target occupied: ${target} resolves outside the repository`;
|
|
103
|
+
return null;
|
|
104
|
+
});
|
|
105
|
+
|
|
106
|
+
const writeGateLines = Effect.fn("verifySkill.writeGateLines")(function* (
|
|
107
|
+
targets: ReadonlyArray<string>,
|
|
108
|
+
) {
|
|
109
|
+
const files = yield* AgentDocsFiles;
|
|
110
|
+
// The working folder is the physical path, as `pwd -P` prints it.
|
|
111
|
+
const root = yield* files.workingFolder;
|
|
112
|
+
const lines: Array<string> = [];
|
|
113
|
+
for (const target of targets) {
|
|
114
|
+
const line = yield* refusal(root, target);
|
|
115
|
+
if (line !== null) lines.push(line);
|
|
116
|
+
}
|
|
117
|
+
return lines;
|
|
118
|
+
});
|
|
119
|
+
|
|
120
|
+
/** Run `verify-skill <args>` and return its exit status; a usage error fails with UsageError. */
|
|
121
|
+
export const runVerifySkill = Effect.fn("verifySkill.run")(function* (args: ReadonlyArray<string>) {
|
|
122
|
+
const files = yield* AgentDocsFiles;
|
|
123
|
+
const [command, ...rest] = args;
|
|
124
|
+
let result: VerifySkillResult;
|
|
125
|
+
if (command === "detect" && rest.length === 0) result = yield* verifySkillLines();
|
|
126
|
+
else if (command === "write-gate" && rest.length > 0)
|
|
127
|
+
result = { ok: true, lines: yield* writeGateLines(rest) };
|
|
128
|
+
else if (command === "entry-gate" && rest.length === 0)
|
|
129
|
+
result = {
|
|
130
|
+
ok: true,
|
|
131
|
+
lines: (yield* files.entryExists(SKILL_DIR)) ? [`target occupied: ${SKILL_DIR} exists`] : [],
|
|
132
|
+
};
|
|
133
|
+
else return yield* new UsageError({ usage: USAGE });
|
|
134
|
+
yield* printLines(result.lines);
|
|
135
|
+
return result.ok ? 0 : 2;
|
|
136
|
+
});
|
package/cli/src/argv.ts
CHANGED
|
@@ -6,6 +6,9 @@ import { updateCommand } from "./commands/update";
|
|
|
6
6
|
import { ompCommand } from "./commands/omp";
|
|
7
7
|
import { scratchCommand } from "./commands/scratch";
|
|
8
8
|
import { tidyCommand } from "./commands/tidy";
|
|
9
|
+
import { planCommand } from "./commands/plan";
|
|
10
|
+
import { agentDocsCommand } from "./commands/agentDocs";
|
|
11
|
+
import { skillCommand } from "./commands/skill";
|
|
9
12
|
import {
|
|
10
13
|
buildSurfaces,
|
|
11
14
|
normalizeArgv,
|
|
@@ -32,6 +35,9 @@ export const COMMANDS = [
|
|
|
32
35
|
ompCommand,
|
|
33
36
|
scratchCommand,
|
|
34
37
|
tidyCommand,
|
|
38
|
+
planCommand,
|
|
39
|
+
agentDocsCommand,
|
|
40
|
+
skillCommand,
|
|
35
41
|
] as const;
|
|
36
42
|
|
|
37
43
|
const SURFACES: ArgvSurfaces = buildSurfaces(COMMANDS, GlobalFlag.BuiltIns);
|
|
@@ -46,9 +52,27 @@ const reject = (message: string): ArgvOutcome => ({
|
|
|
46
52
|
export const subcommandName = (args: ReadonlyArray<string>): string | undefined =>
|
|
47
53
|
scanSubcommandName(args, SURFACES);
|
|
48
54
|
|
|
55
|
+
// `docks-kit plan`, `docks-kit agent-docs`, and `docks-kit skill` pass every later word to their dispatcher, which
|
|
56
|
+
// parses them as the former scripts did, so a `--` after the command word keeps Effect from reading them as flags or
|
|
57
|
+
// adding its own refusal.
|
|
58
|
+
const RAW_PASSTHROUGH: ReadonlySet<string> = new Set(["plan", "agent-docs", "skill"]);
|
|
59
|
+
|
|
60
|
+
const spliceRawBoundary = (args: ReadonlyArray<string>, word: string): ReadonlyArray<string> => {
|
|
61
|
+
const index = args.findIndex(
|
|
62
|
+
(token, at) => token === word && subcommandName(args.slice(0, at + 1)) === word,
|
|
63
|
+
);
|
|
64
|
+
return [...args.slice(0, index + 1), "--", ...args.slice(index + 1)];
|
|
65
|
+
};
|
|
66
|
+
|
|
67
|
+
const passthroughBoundary = (args: ReadonlyArray<string>): ReadonlyArray<string> => {
|
|
68
|
+
const word = subcommandName(args);
|
|
69
|
+
if (word === "omp") return spliceOmpBoundary(args, SURFACES);
|
|
70
|
+
return word !== undefined && RAW_PASSTHROUGH.has(word) ? spliceRawBoundary(args, word) : args;
|
|
71
|
+
};
|
|
72
|
+
|
|
49
73
|
/** Validate the argument list, then hand back the arguments Effect 4 should parse. */
|
|
50
74
|
export const prepareArgv = (args: ReadonlyArray<string>): ArgvOutcome => {
|
|
51
|
-
const boundaryArgs =
|
|
75
|
+
const boundaryArgs = passthroughBoundary(args);
|
|
52
76
|
const subcommand = subcommandName(boundaryArgs);
|
|
53
77
|
const commandSurface =
|
|
54
78
|
subcommand === undefined ? undefined : SURFACES.commandSurfaces.get(subcommand);
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { Argument, Command } from "effect/cli";
|
|
2
|
+
import { Effect } from "effect";
|
|
3
|
+
|
|
4
|
+
import { runAgentDocs } from "../agentDocs/commands";
|
|
5
|
+
import { AgentDocsServicesLive } from "../agentDocs/services";
|
|
6
|
+
|
|
7
|
+
// `argv.ts` puts a `--` after the `agent-docs` word, so every later word reaches the agent-docs dispatcher as it was
|
|
8
|
+
// given, and each helper refuses an unknown argument with its own usage line.
|
|
9
|
+
const args: Argument.Argument<ReadonlyArray<string>> = Argument.String("args").pipe(
|
|
10
|
+
Argument.withDescription(
|
|
11
|
+
"pr-template detect|gate, verify-skill detect|write-gate <path>...|entry-gate, agent-first detect|check|convert-agent <path>, bridge-check audit|verify [--expect <path>]...",
|
|
12
|
+
),
|
|
13
|
+
Argument.variadic(),
|
|
14
|
+
);
|
|
15
|
+
|
|
16
|
+
export const agentDocsCommand = Command.make("agent-docs", { args }, (config) =>
|
|
17
|
+
runAgentDocs(config.args).pipe(
|
|
18
|
+
Effect.flatMap((code) =>
|
|
19
|
+
Effect.sync(() => {
|
|
20
|
+
process.exitCode = code;
|
|
21
|
+
}),
|
|
22
|
+
),
|
|
23
|
+
Effect.provide(AgentDocsServicesLive),
|
|
24
|
+
),
|
|
25
|
+
).pipe(
|
|
26
|
+
Command.withDescription(
|
|
27
|
+
"Agent-doc checks of the agent-first-setup, claude-md-migration, and plan-workspace skills: pull-request templates, the verify skill, the agent-first check, and the CLAUDE.md bridge check.",
|
|
28
|
+
),
|
|
29
|
+
);
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { Argument, Command } from "effect/cli";
|
|
2
|
+
import { Effect } from "effect";
|
|
3
|
+
|
|
4
|
+
import { runPlan } from "../plan/commands";
|
|
5
|
+
import { PlanServicesLive } from "../plan/services";
|
|
6
|
+
|
|
7
|
+
// `argv.ts` puts a `--` after the `plan` word, so every later word reaches the plan dispatcher as it was given, and
|
|
8
|
+
// the dispatcher refuses an unknown argument with the words of the plan contract.
|
|
9
|
+
const args: Argument.Argument<ReadonlyArray<string>> = Argument.String("args").pipe(
|
|
10
|
+
Argument.withDescription(
|
|
11
|
+
"new|show|export|edit|status|step|list|archive|retire|reopen|base-blob|checkout-state and their arguments",
|
|
12
|
+
),
|
|
13
|
+
Argument.variadic(),
|
|
14
|
+
);
|
|
15
|
+
|
|
16
|
+
export const planCommand = Command.make("plan", { args }, (config) =>
|
|
17
|
+
runPlan(config.args).pipe(
|
|
18
|
+
Effect.flatMap((code) =>
|
|
19
|
+
Effect.sync(() => {
|
|
20
|
+
process.exitCode = code;
|
|
21
|
+
}),
|
|
22
|
+
),
|
|
23
|
+
Effect.provide(PlanServicesLive),
|
|
24
|
+
),
|
|
25
|
+
).pipe(
|
|
26
|
+
Command.withDescription(
|
|
27
|
+
"Plan lifecycle helper of the plan-manager skill: GitHub plan issues, plan exports and edits, and checkout snapshots.",
|
|
28
|
+
),
|
|
29
|
+
);
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { Argument, Command } from "effect/cli";
|
|
2
|
+
import { Effect } from "effect";
|
|
3
|
+
|
|
4
|
+
import { runSkill } from "../skills/commands";
|
|
5
|
+
import { SkillFiles } from "../skills/files";
|
|
6
|
+
|
|
7
|
+
// `argv.ts` puts a `--` after the `skill` word, so every later word reaches the skill dispatcher as it was given, and
|
|
8
|
+
// the dispatcher answers a word it does not know with its own usage line.
|
|
9
|
+
const args: Argument.Argument<ReadonlyArray<string>> = Argument.String("args").pipe(
|
|
10
|
+
Argument.withDescription(
|
|
11
|
+
"guard [--strict] <skill-dir|skills-root>..., score [--per-file] [skills-root] (default .agents/skills)",
|
|
12
|
+
),
|
|
13
|
+
Argument.variadic(),
|
|
14
|
+
);
|
|
15
|
+
|
|
16
|
+
export const skillCommand = Command.make("skill", { args }, (config) =>
|
|
17
|
+
runSkill(config.args).pipe(
|
|
18
|
+
Effect.flatMap((code) =>
|
|
19
|
+
Effect.sync(() => {
|
|
20
|
+
process.exitCode = code;
|
|
21
|
+
}),
|
|
22
|
+
),
|
|
23
|
+
Effect.provide(SkillFiles.layer),
|
|
24
|
+
),
|
|
25
|
+
).pipe(
|
|
26
|
+
Command.withDescription(
|
|
27
|
+
"SKILL.md checks of the write-skill and skill-maintenance skills: the portable validator and the 16-point docks rubric score.",
|
|
28
|
+
),
|
|
29
|
+
);
|
|
@@ -1,9 +1,10 @@
|
|
|
1
1
|
import { Command, Flag } from "effect/cli";
|
|
2
2
|
import { Console, Effect } from "effect";
|
|
3
|
+
import type { SpawnSyncOptions, SpawnSyncReturns } from "node:child_process";
|
|
3
4
|
import { existsSync, readFileSync } from "node:fs";
|
|
4
|
-
import {
|
|
5
|
+
import { join } from "node:path";
|
|
6
|
+
import { bail } from "../engine";
|
|
5
7
|
import { kitHome } from "../kitHome";
|
|
6
|
-
import { DEPENDENCIES, defaultProbeExecutor, resolvePath } from "../engine-native/deps";
|
|
7
8
|
import { p, spawnHost } from "../engine-native/exec";
|
|
8
9
|
import { hostOs, type HostOs } from "../engine-native/os";
|
|
9
10
|
|
|
@@ -12,8 +13,19 @@ const noSync = Flag.Boolean("no-sync").pipe(
|
|
|
12
13
|
Flag.withDefault(false),
|
|
13
14
|
);
|
|
14
15
|
|
|
15
|
-
|
|
16
|
-
|
|
16
|
+
/** The host spawn of an update. Tests pass a recorder to observe the children. */
|
|
17
|
+
type UpdateSpawn = (
|
|
18
|
+
command: string,
|
|
19
|
+
args: ReadonlyArray<string>,
|
|
20
|
+
overrides?: SpawnSyncOptions,
|
|
21
|
+
) => SpawnSyncReturns<string>;
|
|
22
|
+
|
|
23
|
+
const git = (
|
|
24
|
+
spawn: UpdateSpawn,
|
|
25
|
+
home: string,
|
|
26
|
+
args: Array<string>,
|
|
27
|
+
): { ok: boolean; out: string } => {
|
|
28
|
+
const res = spawn("git", ["-C", home, ...args]);
|
|
17
29
|
return {
|
|
18
30
|
ok: res.error === undefined && res.status === 0,
|
|
19
31
|
out: `${res.stdout ?? ""}${res.stderr ?? ""}`.trim(),
|
|
@@ -22,13 +34,49 @@ const git = (home: string, args: Array<string>): { ok: boolean; out: string } =>
|
|
|
22
34
|
|
|
23
35
|
/** Spawn the freshly-updated code — the running process still has the old
|
|
24
36
|
* version loaded, so the chained sync must be a new process. */
|
|
25
|
-
const chainSync = (
|
|
37
|
+
const chainSync = (spawn: UpdateSpawn, args: Array<string>): Effect.Effect<void> =>
|
|
26
38
|
Effect.sync(() => {
|
|
27
|
-
const res =
|
|
39
|
+
const res = spawn(process.execPath, args, { stdio: "inherit" });
|
|
28
40
|
if (res.error !== undefined || res.status !== 0) process.exit(res.status ?? 1);
|
|
29
41
|
});
|
|
30
42
|
|
|
31
|
-
|
|
43
|
+
type PackageBinEntry =
|
|
44
|
+
| { readonly ok: true; readonly entry: string }
|
|
45
|
+
| { readonly ok: false; readonly diagnostic: string };
|
|
46
|
+
|
|
47
|
+
/** The file that the installed package's `bin` names. The chained sync runs
|
|
48
|
+
* it, not a fixed path, because `@latest` can be a release that predates the
|
|
49
|
+
* bundle and still names `cli/src/main.ts`. The host's `join` builds the
|
|
50
|
+
* spawned path, so a Windows home gets one separator style. */
|
|
51
|
+
const packageBinEntry = (home: string): PackageBinEntry => {
|
|
52
|
+
const manifestPath = join(home, "package.json");
|
|
53
|
+
let doc: unknown;
|
|
54
|
+
try {
|
|
55
|
+
doc = JSON.parse(readFileSync(manifestPath, "utf8"));
|
|
56
|
+
} catch {
|
|
57
|
+
doc = undefined;
|
|
58
|
+
}
|
|
59
|
+
const bin = doc !== null && typeof doc === "object" && "bin" in doc ? doc.bin : undefined;
|
|
60
|
+
const named =
|
|
61
|
+
typeof bin === "string"
|
|
62
|
+
? bin
|
|
63
|
+
: bin !== null && typeof bin === "object" && "docks-kit" in bin
|
|
64
|
+
? bin["docks-kit"]
|
|
65
|
+
: undefined;
|
|
66
|
+
if (typeof named !== "string" || named === "") {
|
|
67
|
+
return {
|
|
68
|
+
ok: false,
|
|
69
|
+
diagnostic: `global package update completed, but ${manifestPath} names no docks-kit bin`,
|
|
70
|
+
};
|
|
71
|
+
}
|
|
72
|
+
const entry = join(home, named);
|
|
73
|
+
return existsSync(entry)
|
|
74
|
+
? { ok: true, entry }
|
|
75
|
+
: {
|
|
76
|
+
ok: false,
|
|
77
|
+
diagnostic: `global package update completed, but the docks-kit bin ${entry} named by ${manifestPath} does not exist`,
|
|
78
|
+
};
|
|
79
|
+
};
|
|
32
80
|
|
|
33
81
|
const readPackageVersion = (home: string): string => {
|
|
34
82
|
try {
|
|
@@ -50,14 +98,16 @@ interface PackageRootCapture {
|
|
|
50
98
|
|
|
51
99
|
type CapturePackageRoot = (command: string, args: ReadonlyArray<string>) => PackageRootCapture;
|
|
52
100
|
|
|
53
|
-
const capturePackageRoot
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
101
|
+
const capturePackageRoot =
|
|
102
|
+
(spawn: UpdateSpawn): CapturePackageRoot =>
|
|
103
|
+
(command, args) => {
|
|
104
|
+
const res = spawn(command, args);
|
|
105
|
+
return {
|
|
106
|
+
status: res.status,
|
|
107
|
+
stdout: res.stdout ?? "",
|
|
108
|
+
...(res.error === undefined ? {} : { error: res.error }),
|
|
109
|
+
};
|
|
59
110
|
};
|
|
60
|
-
};
|
|
61
111
|
|
|
62
112
|
/**
|
|
63
113
|
* The comparison key of a host path. Windows reports paths with backslashes
|
|
@@ -100,7 +150,7 @@ export type GlobalPackageHome =
|
|
|
100
150
|
|
|
101
151
|
export const resolveGlobalPackageHome = (
|
|
102
152
|
manager: PackageManager,
|
|
103
|
-
capture: CapturePackageRoot = capturePackageRoot,
|
|
153
|
+
capture: CapturePackageRoot = capturePackageRoot(spawnHost),
|
|
104
154
|
): GlobalPackageHome => {
|
|
105
155
|
const commandArgs = manager === "bun" ? ["pm", "-g", "ls"] : ["root", "-g"];
|
|
106
156
|
const result = capture(manager, commandArgs);
|
|
@@ -153,69 +203,47 @@ export const packageUpdateResult = (
|
|
|
153
203
|
return { alreadyCurrent: false, message: `Updated ${before} -> ${after}.` };
|
|
154
204
|
};
|
|
155
205
|
|
|
156
|
-
export
|
|
157
|
-
| { readonly ok: true; readonly command: string }
|
|
158
|
-
| { readonly ok: false; readonly diagnostic: string };
|
|
159
|
-
|
|
160
|
-
/**
|
|
161
|
-
* The Bun that reinstalls checkout dependencies. The source path always runs
|
|
162
|
-
* under Bun, and the launcher may have picked a Bun that is not on PATH, so it
|
|
163
|
-
* reuses `execPath`. A compiled binary resolves Bun like the dependency probe:
|
|
164
|
-
* PATH, then $BUN_INSTALL/bin, then ~/.bun/bin.
|
|
165
|
-
*/
|
|
166
|
-
export const updateBunCommand = async (
|
|
167
|
-
isCompiled: boolean,
|
|
168
|
-
execPath: string,
|
|
169
|
-
home: string,
|
|
170
|
-
resolveBun: () => Promise<string> = () => resolvePath(DEPENDENCIES.bun, defaultProbeExecutor),
|
|
171
|
-
): Promise<UpdateBunCommand> => {
|
|
172
|
-
if (!isCompiled) return { ok: true, command: execPath };
|
|
173
|
-
const resolved = await resolveBun();
|
|
174
|
-
return resolved === ""
|
|
175
|
-
? {
|
|
176
|
-
ok: false,
|
|
177
|
-
diagnostic: `dependencies changed but Bun was not found - run 'bun install --frozen-lockfile' in ${home}, then docks-kit sync`,
|
|
178
|
-
}
|
|
179
|
-
: { ok: true, command: resolved };
|
|
180
|
-
};
|
|
181
|
-
|
|
182
|
-
const updateCheckout = (home: string, skipSync: boolean) =>
|
|
206
|
+
export const updateCheckout = (home: string, skipSync: boolean, spawn: UpdateSpawn = spawnHost) =>
|
|
183
207
|
Effect.gen(function* () {
|
|
184
|
-
if (
|
|
208
|
+
if (spawn("git", ["--version"], { stdio: "ignore" }).status !== 0) {
|
|
185
209
|
return yield* bail("git not found - cannot update the kit checkout");
|
|
186
210
|
}
|
|
187
|
-
const dirty = git(home, ["status", "--porcelain"]);
|
|
211
|
+
const dirty = git(spawn, home, ["status", "--porcelain"]);
|
|
188
212
|
if (!dirty.ok) return yield* bail(`git status failed in ${home}: ${dirty.out}`);
|
|
189
213
|
if (dirty.out !== "") {
|
|
190
214
|
return yield* bail(
|
|
191
215
|
`kit checkout ${home} has local changes - commit or stash them, then re-run docks-kit update`,
|
|
192
216
|
);
|
|
193
217
|
}
|
|
194
|
-
const upstream = git(home, [
|
|
218
|
+
const upstream = git(spawn, home, [
|
|
219
|
+
"rev-parse",
|
|
220
|
+
"--abbrev-ref",
|
|
221
|
+
"--symbolic-full-name",
|
|
222
|
+
"@{u}",
|
|
223
|
+
]);
|
|
195
224
|
if (!upstream.ok) {
|
|
196
225
|
return yield* bail(
|
|
197
226
|
"current branch has no upstream - set one (git branch --set-upstream-to) or update manually",
|
|
198
227
|
);
|
|
199
228
|
}
|
|
200
|
-
const before = git(home, ["rev-parse", "HEAD"]).out;
|
|
201
|
-
const pull = git(home, ["pull", "--ff-only"]);
|
|
229
|
+
const before = git(spawn, home, ["rev-parse", "HEAD"]).out;
|
|
230
|
+
const pull = git(spawn, home, ["pull", "--ff-only"]);
|
|
202
231
|
if (!pull.ok) return yield* bail(`git pull --ff-only failed (diverged history?):\n${pull.out}`);
|
|
203
|
-
const after = git(home, ["rev-parse", "HEAD"]).out;
|
|
232
|
+
const after = git(spawn, home, ["rev-parse", "HEAD"]).out;
|
|
204
233
|
|
|
205
234
|
// A current kit still syncs: the sync repairs drift of the deployed files
|
|
206
235
|
// and plugins, for example a pi-intercom install that left its pin.
|
|
207
236
|
const changed = before !== after;
|
|
208
237
|
if (changed) {
|
|
209
|
-
const count = git(home, ["rev-list", "--count", `${before}..${after}`]).out;
|
|
238
|
+
const count = git(spawn, home, ["rev-list", "--count", `${before}..${after}`]).out;
|
|
210
239
|
yield* Console.log(
|
|
211
240
|
`Updated ${before.slice(0, 7)}..${after.slice(0, 7)} (${count} commit(s) from ${upstream.out}).`,
|
|
212
241
|
);
|
|
213
242
|
|
|
214
|
-
const touched = git(home, ["diff", "--name-only", before, after]).out.split("\n");
|
|
243
|
+
const touched = git(spawn, home, ["diff", "--name-only", before, after]).out.split("\n");
|
|
215
244
|
if (touched.includes("bun.lock") || touched.includes("package.json")) {
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
const res = spawnHost(bun.command, ["install", "--frozen-lockfile"], {
|
|
245
|
+
// The launcher may run a Bun that is not on PATH, so reuse the running one.
|
|
246
|
+
const res = spawn(process.execPath, ["install", "--frozen-lockfile"], {
|
|
219
247
|
cwd: home,
|
|
220
248
|
stdio: "inherit",
|
|
221
249
|
});
|
|
@@ -232,13 +260,6 @@ const updateCheckout = (home: string, skipSync: boolean) =>
|
|
|
232
260
|
);
|
|
233
261
|
}
|
|
234
262
|
|
|
235
|
-
if (compiled) {
|
|
236
|
-
return yield* Console.log(
|
|
237
|
-
changed
|
|
238
|
-
? "This compiled binary still runs the previous version - the checkout launcher will use updated source next time. Run: ./docks-kit sync (rebuild with bash cli/build-binaries.sh to restore the binary fast path)."
|
|
239
|
-
: "This compiled binary cannot chain the sync. Run: ./docks-kit sync",
|
|
240
|
-
);
|
|
241
|
-
}
|
|
242
263
|
if (skipSync)
|
|
243
264
|
return yield* Console.log(
|
|
244
265
|
changed ? "Kit updated. Run: docks-kit sync" : "Run: docks-kit sync",
|
|
@@ -248,16 +269,17 @@ const updateCheckout = (home: string, skipSync: boolean) =>
|
|
|
248
269
|
? "Kit updated - running sync with the new version..."
|
|
249
270
|
: "Syncing to deliver plugin and config updates...",
|
|
250
271
|
);
|
|
251
|
-
|
|
272
|
+
// The source, also when the checkout holds a stale ignored bundle.
|
|
273
|
+
return yield* chainSync(spawn, [join(home, "cli", "src", "main.ts"), "sync"]);
|
|
252
274
|
});
|
|
253
275
|
|
|
254
|
-
const updatePackage = (home: string, skipSync: boolean) =>
|
|
276
|
+
export const updatePackage = (home: string, skipSync: boolean, spawn: UpdateSpawn = spawnHost) =>
|
|
255
277
|
Effect.gen(function* () {
|
|
256
278
|
const manager = packageManagerForHome(home);
|
|
257
279
|
const beforeVersion = readPackageVersion(home);
|
|
258
280
|
const updateArgs =
|
|
259
281
|
manager === "bun" ? ["add", "-g", "docks-kit@latest"] : ["install", "-g", "docks-kit@latest"];
|
|
260
|
-
const res =
|
|
282
|
+
const res = spawn(manager, updateArgs, { stdio: "inherit" });
|
|
261
283
|
if (res.error !== undefined || res.status !== 0) {
|
|
262
284
|
return yield* bail(
|
|
263
285
|
`global package update failed (${manager === "bun" ? "bun add -g" : "npm install -g"} docks-kit@latest)`,
|
|
@@ -265,7 +287,7 @@ const updatePackage = (home: string, skipSync: boolean) =>
|
|
|
265
287
|
);
|
|
266
288
|
}
|
|
267
289
|
|
|
268
|
-
const updated = resolveGlobalPackageHome(manager);
|
|
290
|
+
const updated = resolveGlobalPackageHome(manager, capturePackageRoot(spawn));
|
|
269
291
|
if (!updated.ok) {
|
|
270
292
|
return yield* bail(
|
|
271
293
|
`global package update completed, but the updated package root could not be resolved: ${updated.diagnostic}`,
|
|
@@ -289,12 +311,14 @@ const updatePackage = (home: string, skipSync: boolean) =>
|
|
|
289
311
|
return yield* Console.log(
|
|
290
312
|
result.alreadyCurrent ? "Run: docks-kit sync" : "Kit updated. Run: docks-kit sync",
|
|
291
313
|
);
|
|
314
|
+
const bin = packageBinEntry(updated.home);
|
|
315
|
+
if (!bin.ok) return yield* bail(bin.diagnostic, 1);
|
|
292
316
|
yield* Console.log(
|
|
293
317
|
result.alreadyCurrent
|
|
294
318
|
? "Syncing to deliver plugin and config updates..."
|
|
295
319
|
: "Kit updated - running sync with the new version...",
|
|
296
320
|
);
|
|
297
|
-
return yield* chainSync(
|
|
321
|
+
return yield* chainSync(spawn, [bin.entry, "sync"]);
|
|
298
322
|
});
|
|
299
323
|
|
|
300
324
|
export const updateCommand = Command.make("update", { noSync }, (config) =>
|
|
@@ -307,7 +331,7 @@ export const updateCommand = Command.make("update", { noSync }, (config) =>
|
|
|
307
331
|
return yield* updatePackage(home, config.noSync);
|
|
308
332
|
}
|
|
309
333
|
return yield* bail(
|
|
310
|
-
`kit home ${home} is neither a git checkout nor a global package install -
|
|
334
|
+
`kit home ${home} is neither a git checkout nor a global package install - reinstall the kit as a git checkout or with 'bun add -g docks-kit'`,
|
|
311
335
|
);
|
|
312
336
|
}),
|
|
313
337
|
).pipe(
|
|
@@ -204,15 +204,16 @@ active logger binding.
|
|
|
204
204
|
output, and the channel and migration invariants to
|
|
205
205
|
`cli/test/goldens/mutation.json`.
|
|
206
206
|
- `.github/workflows/parity.yml` runs its portable lane on `ubuntu-24.04` and
|
|
207
|
-
`macos-26`: generated-payload check, typecheck, unit tests, a clean-room
|
|
208
|
-
package install smoke
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
- `.github/workflows/release-cli.yml`
|
|
215
|
-
|
|
207
|
+
`macos-26`: generated-payload check, typecheck, unit tests, and a clean-room
|
|
208
|
+
package install smoke. On `windows-2025`, two unit-test shards and the
|
|
209
|
+
`portable-windows-checks` job (generated-payload check, typecheck, and a
|
|
210
|
+
global install that runs the bundle) run in parallel. The check
|
|
211
|
+
`portable (windows-2025)` passes only when all three pass. The
|
|
212
|
+
Linux-canonical snapshot lane stays on Ubuntu and runs both golden suites
|
|
213
|
+
plus their prove-red checks.
|
|
214
|
+
- `.github/workflows/release-cli.yml` attaches the bundle's source map
|
|
215
|
+
`docks-kit.js.map` to the GitHub release and publishes the npm package with
|
|
216
|
+
provenance.
|
|
216
217
|
|
|
217
218
|
## Non-Goals
|
|
218
219
|
|
|
@@ -1,16 +1,9 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Host
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
* - the artifact names and `uname` keys in the Bash launcher `docks-kit`;
|
|
8
|
-
* - the artifact name and processor architecture in `docks-kit.ps1`;
|
|
9
|
-
* - the default `TARGETS` list of `cli/build-binaries.sh`;
|
|
10
|
-
* - the four artifact names in each of the two lists of
|
|
11
|
-
* `.github/workflows/release-cli.yml`: the `with.path` list of the
|
|
12
|
-
* `actions/upload-artifact` step in job `build`, and the `for asset in`
|
|
13
|
-
* list of the `gh release upload` step in job `github-release`.
|
|
2
|
+
* Host support map (Platform seam in DESIGN.md). Each of the two launchers
|
|
3
|
+
* checks the host by hand before it runs Bun from source, so
|
|
4
|
+
* `cli/test/unit/hostTargets.test.ts` checks them against this table:
|
|
5
|
+
* - the `uname` keys in the Bash launcher `docks-kit`;
|
|
6
|
+
* - the processor architecture in `docks-kit.ps1`.
|
|
14
7
|
* The same test also checks two facts outside this table: the generated Bun
|
|
15
8
|
* pin in the two launchers and the two installers equals the
|
|
16
9
|
* `SoT/toolchain.json` pin, and `docks-kit.ps1` and `install.ps1` hold only
|
|
@@ -30,10 +23,6 @@ export interface HostTarget {
|
|
|
30
23
|
readonly id: TargetId;
|
|
31
24
|
readonly platform: PlatformName;
|
|
32
25
|
readonly arch: TargetArch;
|
|
33
|
-
/** `bun build --compile --target=` value. */
|
|
34
|
-
readonly bunTarget: string;
|
|
35
|
-
/** Compiled binary file name, including the Windows `.exe` suffix. */
|
|
36
|
-
readonly artifact: string;
|
|
37
26
|
/** `uname -s`-`uname -m` keys the Bash launcher matches; empty on Windows. */
|
|
38
27
|
readonly unameKeys: ReadonlyArray<string>;
|
|
39
28
|
/**
|
|
@@ -54,8 +43,6 @@ const target = (
|
|
|
54
43
|
id,
|
|
55
44
|
platform,
|
|
56
45
|
arch,
|
|
57
|
-
bunTarget: `bun-${id}`,
|
|
58
|
-
artifact: platform === "windows" ? `docks-kit-${id}.exe` : `docks-kit-${id}`,
|
|
59
46
|
unameKeys,
|
|
60
47
|
processorArchitectures,
|
|
61
48
|
});
|
|
@@ -71,7 +58,7 @@ function targetFor(platform: PlatformName, arch: string): HostTarget | undefined
|
|
|
71
58
|
return HOST_TARGETS.find((t) => t.platform === platform && t.arch === arch);
|
|
72
59
|
}
|
|
73
60
|
|
|
74
|
-
/** Resolve the
|
|
61
|
+
/** Resolve the supported host target for a raw Node platform/arch pair. */
|
|
75
62
|
export function targetForHost(platform: NodeJS.Platform, arch: string): HostTarget | undefined {
|
|
76
63
|
return targetFor(platformName(platform), arch);
|
|
77
64
|
}
|
package/cli/src/engine.ts
CHANGED
|
@@ -21,12 +21,6 @@ const requireSupportedHost = () => {
|
|
|
21
21
|
);
|
|
22
22
|
};
|
|
23
23
|
|
|
24
|
-
// In a compiled executable process.execPath IS the CLI, so a re-spawn must
|
|
25
|
-
// not pass main.ts. Guarded because the unit suite imports this module under
|
|
26
|
-
// Node, where the `Bun` global is absent; only a Bun-hosted standalone
|
|
27
|
-
// executable can be compiled, so absence means false.
|
|
28
|
-
export const compiled: boolean = typeof Bun !== "undefined" && Bun.isStandaloneExecutable === true;
|
|
29
|
-
|
|
30
24
|
const failureMessage = (error: unknown): string => {
|
|
31
25
|
if (error instanceof Error && error.message !== "") return error.message;
|
|
32
26
|
return typeof error === "string" && error !== "" ? error : "unknown error";
|