aligndev 0.28.1 → 0.29.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/README.md +13 -5
- package/dist/alignfirst-cli.js +21 -8
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +16 -4
- package/dist/code/claude-agent.js +1 -1
- package/dist/code/code-cli.js +2 -4
- package/dist/code/codex-agent.js +1 -1
- package/dist/code/machine-id.js +14 -3
- package/dist/code/pi-agent.js +1 -1
- package/dist/code/run-agent.js +37 -1
- package/dist/command-form.d.ts +5 -2
- package/dist/command-form.js +15 -6
- package/dist/guide/code-guide.d.ts +2 -2
- package/dist/guide/code-guide.js +4 -8
- package/dist/guide/guide-cli.js +84 -29
- package/dist/guide/render-template.d.ts +4 -0
- package/dist/guide/render-template.js +51 -12
- package/dist/guide/topics.d.ts +8 -3
- package/dist/guide/topics.js +26 -7
- package/dist/project/plans.js +1 -1
- package/dist/worktree/add.d.ts +3 -13
- package/dist/worktree/add.js +7 -101
- package/dist/worktree/setup.d.ts +18 -0
- package/dist/worktree/setup.js +192 -0
- package/dist/worktree/worktree-cli.js +29 -11
- package/package.json +4 -1
- package/templates/guide/code.md +12 -3
- package/templates/guide/playbook/channel-handling.md +12 -17
- package/templates/guide/playbook/consultation.md +24 -17
- package/templates/guide/playbook/dispatcher.md +18 -0
- package/templates/guide/playbook/{discord-message-tool.md → message-tool.md} +29 -0
- package/templates/guide/playbook/playbook.md +53 -20
- package/templates/guide/playbook/project-lifecycle.md +26 -11
- package/templates/guide/playbook/project-workspace-setup.md +87 -62
- package/templates/guide/playbook/work-files-setup.md +1 -1
- package/templates/guide/playbook/working-session.md +195 -112
- package/templates/guide/playbook/slack-message-tool.md +0 -23
|
@@ -1,27 +1,43 @@
|
|
|
1
1
|
import { PLATFORMS } from "../config.js";
|
|
2
2
|
import { readTemplate } from "../templates.js";
|
|
3
|
+
export const SURFACES = ["slack", "discord", "app"];
|
|
3
4
|
const GUIDE_FILE_CONDITIONS = ["developers", "readme", "noGuide"];
|
|
4
5
|
// Active for both guide files: `developers` and `readme`.
|
|
5
6
|
const HAS_GUIDE = "hasGuide";
|
|
7
|
+
// Derived facts: `thread` holds on Slack and Discord; `conversation` in an app conversation and
|
|
8
|
+
// under codingAgent.
|
|
9
|
+
const THREAD = "thread";
|
|
10
|
+
const CONVERSATION = "conversation";
|
|
6
11
|
const MARKER = /^\{\{([#/])([A-Za-z]+)\}\}$/;
|
|
7
|
-
// Renders `templates/guide/<name>`: the blocks first, then the placeholders — the command forms
|
|
8
|
-
// and every key of `values`.
|
|
12
|
+
// Renders `templates/guide/<name>`: the blocks first, then the placeholders — the command forms,
|
|
13
|
+
// the guide command of the render, and every key of `values`.
|
|
9
14
|
export function renderGuideTemplate(name, active, forms, values = {}) {
|
|
10
15
|
const placeholders = {
|
|
11
16
|
ALIGNDEV: forms.aligndev,
|
|
12
17
|
ALIGNFIRST: forms.alignfirst,
|
|
18
|
+
...guidePlaceholder(active, forms),
|
|
19
|
+
BACKGROUND_COMMAND_JSON: JSON.stringify(`${forms.aligndev} code new --message-file '/tmp/aligndev-request.txt' --quiet --meta 'a20bc7c1-c056-4d07-8cc2-90fe491a6df6'`),
|
|
13
20
|
...values,
|
|
14
21
|
};
|
|
15
22
|
let text = renderBlocks(readTemplate(`guide/${name}`), active, name);
|
|
16
23
|
for (const [key, value] of Object.entries(placeholders)) {
|
|
17
|
-
text = text.replaceAll(`{{${key}}}`, value);
|
|
24
|
+
text = text.replaceAll(`{{${key}}}`, () => value);
|
|
18
25
|
}
|
|
19
26
|
return text.trimEnd();
|
|
20
27
|
}
|
|
21
|
-
//
|
|
22
|
-
//
|
|
23
|
-
|
|
24
|
-
|
|
28
|
+
// `{{GUIDE}}` carries the surface into every later guide call. An OpenClaw render without a surface
|
|
29
|
+
// has none.
|
|
30
|
+
function guidePlaceholder(active, forms) {
|
|
31
|
+
if (active.surface !== undefined) {
|
|
32
|
+
return { GUIDE: `${forms.aligndev} guide --channel ${active.surface}` };
|
|
33
|
+
}
|
|
34
|
+
return active.platform === "codingAgent" ? { GUIDE: `${forms.aligndev} guide` } : {};
|
|
35
|
+
}
|
|
36
|
+
// A block is `{{#<name>}}` … `{{/<name>}}`, each marker alone on its line, and names a fact. A
|
|
37
|
+
// platform block sits at the top level. A surface block and `thread` never sit inside a
|
|
38
|
+
// `codingAgent` block; a condition block always does, at any depth; `conversation` sits anywhere.
|
|
39
|
+
// A line is kept when every block around it holds. The runs of empty lines that removed blocks
|
|
40
|
+
// leave collapse to one.
|
|
25
41
|
export function renderBlocks(text, active, templateName) {
|
|
26
42
|
const kept = [];
|
|
27
43
|
const open = [];
|
|
@@ -46,20 +62,34 @@ export function renderBlocks(text, active, templateName) {
|
|
|
46
62
|
return collapseEmptyLines(kept).join("\n");
|
|
47
63
|
}
|
|
48
64
|
function isActive(name, active) {
|
|
65
|
+
if (name === THREAD)
|
|
66
|
+
return active.surface === "slack" || active.surface === "discord";
|
|
67
|
+
if (name === CONVERSATION)
|
|
68
|
+
return active.surface === "app" || active.platform === "codingAgent";
|
|
49
69
|
if (name === HAS_GUIDE)
|
|
50
70
|
return active.guideFile === "developers" || active.guideFile === "readme";
|
|
51
|
-
return name === active.platform || name === active.guideFile;
|
|
71
|
+
return name === active.platform || name === active.surface || name === active.guideFile;
|
|
52
72
|
}
|
|
53
73
|
function openBlock(name, line, open, templateName) {
|
|
54
|
-
const
|
|
74
|
+
const insideCodingAgent = open.some((block) => block.name === "codingAgent");
|
|
55
75
|
if (isPlatform(name)) {
|
|
76
|
+
const outer = open.at(-1);
|
|
56
77
|
if (outer !== undefined) {
|
|
57
78
|
throw blockError(templateName, line, `platform block "${name}" inside "${outer.name}"`);
|
|
58
79
|
}
|
|
59
80
|
return { name, line };
|
|
60
81
|
}
|
|
82
|
+
if (isSurface(name) || name === THREAD) {
|
|
83
|
+
if (insideCodingAgent) {
|
|
84
|
+
const block = isSurface(name) ? `surface block "${name}"` : `block "${name}"`;
|
|
85
|
+
throw blockError(templateName, line, `${block} inside a codingAgent block`);
|
|
86
|
+
}
|
|
87
|
+
return { name, line };
|
|
88
|
+
}
|
|
89
|
+
if (name === CONVERSATION)
|
|
90
|
+
return { name, line };
|
|
61
91
|
if (isCondition(name)) {
|
|
62
|
-
if (
|
|
92
|
+
if (!insideCodingAgent) {
|
|
63
93
|
throw blockError(templateName, line, `condition block "${name}" outside a codingAgent block`);
|
|
64
94
|
}
|
|
65
95
|
return { name, line };
|
|
@@ -67,17 +97,26 @@ function openBlock(name, line, open, templateName) {
|
|
|
67
97
|
throw blockError(templateName, line, `unknown block "${name}"`);
|
|
68
98
|
}
|
|
69
99
|
function closeBlock(name, line, open, templateName) {
|
|
70
|
-
if (!
|
|
100
|
+
if (!isBlockName(name))
|
|
71
101
|
throw blockError(templateName, line, `unknown block "${name}"`);
|
|
72
|
-
}
|
|
73
102
|
if (open.at(-1)?.name !== name) {
|
|
74
103
|
throw blockError(templateName, line, `closing marker "${name}" without its block`);
|
|
75
104
|
}
|
|
76
105
|
open.pop();
|
|
77
106
|
}
|
|
107
|
+
function isBlockName(name) {
|
|
108
|
+
return (isPlatform(name) ||
|
|
109
|
+
isSurface(name) ||
|
|
110
|
+
name === THREAD ||
|
|
111
|
+
name === CONVERSATION ||
|
|
112
|
+
isCondition(name));
|
|
113
|
+
}
|
|
78
114
|
function isPlatform(name) {
|
|
79
115
|
return PLATFORMS.includes(name);
|
|
80
116
|
}
|
|
117
|
+
export function isSurface(name) {
|
|
118
|
+
return SURFACES.includes(name);
|
|
119
|
+
}
|
|
81
120
|
function isCondition(name) {
|
|
82
121
|
return name === HAS_GUIDE || GUIDE_FILE_CONDITIONS.includes(name);
|
|
83
122
|
}
|
package/dist/guide/topics.d.ts
CHANGED
|
@@ -1,3 +1,8 @@
|
|
|
1
|
-
import type
|
|
2
|
-
export declare const PLAYBOOK_DISPATCHER = "
|
|
3
|
-
export declare const
|
|
1
|
+
import { type ActiveBlocks, type Surface } from "./render-template.js";
|
|
2
|
+
export declare const PLAYBOOK_DISPATCHER = "dispatcher";
|
|
3
|
+
export declare const PLAYBOOK = "playbook";
|
|
4
|
+
export declare const ENTRY_TOPICS: readonly string[];
|
|
5
|
+
export declare const PLAYBOOK_TOPICS: Record<GuideContext, readonly string[]>;
|
|
6
|
+
export type GuideContext = "thread" | "app" | "codingAgent";
|
|
7
|
+
export declare function guideContextOf(active: ActiveBlocks): GuideContext;
|
|
8
|
+
export declare function surfacesServing(topic: string): Surface[];
|
package/dist/guide/topics.js
CHANGED
|
@@ -1,17 +1,36 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
//
|
|
1
|
+
import { SURFACES } from "./render-template.js";
|
|
2
|
+
// `templates/guide/playbook/dispatcher.md`, printed by `aligndev guide` without a topic.
|
|
3
|
+
export const PLAYBOOK_DISPATCHER = "dispatcher";
|
|
4
|
+
// `templates/guide/playbook/playbook.md`, the operating instructions.
|
|
5
|
+
export const PLAYBOOK = "playbook";
|
|
6
|
+
// The topics printed after the playbook.
|
|
7
|
+
export const ENTRY_TOPICS = ["working-session", "channel-handling"];
|
|
8
|
+
// The playbook topics each context serves. Every topic is one file of `templates/guide/playbook/`,
|
|
9
|
+
// shared by the contexts through fact blocks.
|
|
5
10
|
export const PLAYBOOK_TOPICS = {
|
|
6
|
-
|
|
11
|
+
thread: [
|
|
7
12
|
"channel-handling",
|
|
8
13
|
"working-session",
|
|
9
14
|
"work-files-setup",
|
|
10
15
|
"project-workspace-setup",
|
|
11
16
|
"project-lifecycle",
|
|
12
17
|
"consultation",
|
|
13
|
-
"
|
|
14
|
-
|
|
18
|
+
"message-tool",
|
|
19
|
+
],
|
|
20
|
+
app: [
|
|
21
|
+
"working-session",
|
|
22
|
+
"work-files-setup",
|
|
23
|
+
"project-workspace-setup",
|
|
24
|
+
"project-lifecycle",
|
|
25
|
+
"consultation",
|
|
15
26
|
],
|
|
16
27
|
codingAgent: ["working-session", "work-files-setup", "project-workspace-setup", "consultation"],
|
|
17
28
|
};
|
|
29
|
+
export function guideContextOf(active) {
|
|
30
|
+
if (active.platform === "codingAgent")
|
|
31
|
+
return "codingAgent";
|
|
32
|
+
return active.surface === "app" ? "app" : "thread";
|
|
33
|
+
}
|
|
34
|
+
export function surfacesServing(topic) {
|
|
35
|
+
return SURFACES.filter((surface) => PLAYBOOK_TOPICS[guideContextOf({ platform: "openclaw", surface })].includes(topic));
|
|
36
|
+
}
|
package/dist/project/plans.js
CHANGED
|
@@ -26,7 +26,7 @@ export function validateEffectivePlans(ctx) {
|
|
|
26
26
|
return value.plans.target;
|
|
27
27
|
}
|
|
28
28
|
catch (error) {
|
|
29
|
-
throw new Error(`${errorMessage(error)}\nSee \`${ctx.forms.aligndev} guide
|
|
29
|
+
throw new Error(`${errorMessage(error)}\nSee the \`work-files-setup\` topic of \`${ctx.forms.aligndev} guide\` for authorized preparation.`);
|
|
30
30
|
}
|
|
31
31
|
}
|
|
32
32
|
function isRecord(value) {
|
package/dist/worktree/add.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import { type Repository
|
|
1
|
+
import { type Repository } from "./git.js";
|
|
2
|
+
import { type WorktreeReport } from "./setup.js";
|
|
2
3
|
import type { WorktreeContext } from "./worktree-cli.js";
|
|
3
4
|
export interface AddOptions {
|
|
4
5
|
path: string;
|
|
@@ -6,15 +7,4 @@ export interface AddOptions {
|
|
|
6
7
|
newBranch: boolean;
|
|
7
8
|
start?: string;
|
|
8
9
|
}
|
|
9
|
-
export
|
|
10
|
-
mainWorktree: string;
|
|
11
|
-
worktree: Worktree;
|
|
12
|
-
directories: Record<".local" | ".plans", DirectoryReport>;
|
|
13
|
-
warnings: string[];
|
|
14
|
-
}
|
|
15
|
-
export interface DirectoryReport {
|
|
16
|
-
path: string;
|
|
17
|
-
mode: "symlink" | "tracked" | "companion" | "absent";
|
|
18
|
-
target: string | null;
|
|
19
|
-
}
|
|
20
|
-
export declare function addWorktree(ctx: WorktreeContext, repo: Repository, options: AddOptions): AddReport;
|
|
10
|
+
export declare function addWorktree(ctx: WorktreeContext, repo: Repository, options: AddOptions): WorktreeReport;
|
package/dist/worktree/add.js
CHANGED
|
@@ -1,22 +1,18 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { dirname,
|
|
1
|
+
import { statSync } from "node:fs";
|
|
2
|
+
import { dirname, resolve } from "node:path";
|
|
3
3
|
import { errorMessage } from "../errors.js";
|
|
4
|
-
import {
|
|
5
|
-
import {
|
|
4
|
+
import { canonicalPath, git, isInside, pathExists } from "./git.js";
|
|
5
|
+
import { finishSetup, prepareDirectories, } from "./setup.js";
|
|
6
6
|
export function addWorktree(ctx, repo, options) {
|
|
7
7
|
const prepared = prepareAdd(ctx, repo, options);
|
|
8
8
|
createGitWorktree(ctx, options, prepared);
|
|
9
|
-
return finishSetup(ctx, repo,
|
|
9
|
+
return finishSetup(ctx, repo, prepared.destination, { directories: prepared.directories, warnings: prepared.warnings }, options.branch);
|
|
10
10
|
}
|
|
11
11
|
function prepareAdd(ctx, repo, options) {
|
|
12
12
|
const destination = validateDestination(ctx, repo, options.path);
|
|
13
13
|
const branch = prepareBranch(ctx, repo, options);
|
|
14
|
-
const
|
|
15
|
-
|
|
16
|
-
const plansTarget = validateEffectivePlans(sourceCtx);
|
|
17
|
-
const warnings = [];
|
|
18
|
-
const directories = planDirectories(sourceCtx, repo, destination, branch.commit, sourceReport, plansTarget, warnings);
|
|
19
|
-
return { destination, branch, directories, warnings };
|
|
14
|
+
const prepared = prepareDirectories(ctx, repo, destination, branch.commit);
|
|
15
|
+
return { destination, branch, ...prepared };
|
|
20
16
|
}
|
|
21
17
|
function validateDestination(ctx, repo, input) {
|
|
22
18
|
const literal = resolve(ctx.cwd, input);
|
|
@@ -71,42 +67,6 @@ function prepareBranch(ctx, repo, options) {
|
|
|
71
67
|
const commit = git(ctx, "rev-parse", "--verify", "--end-of-options", `${start}^{commit}`).trim();
|
|
72
68
|
return { create, start: !create ? options.branch : start, commit, track };
|
|
73
69
|
}
|
|
74
|
-
function planDirectories(ctx, repo, destination, commit, report, plansTarget, warnings) {
|
|
75
|
-
const local = planLocal(ctx, repo, destination, commit, warnings);
|
|
76
|
-
const plans = report.locations[".plans"];
|
|
77
|
-
if (plans.in === "companion") {
|
|
78
|
-
return { ".local": local, ".plans": { path: plans.path, mode: "companion", target: null } };
|
|
79
|
-
}
|
|
80
|
-
if (targetTracks(ctx, commit, ".plans")) {
|
|
81
|
-
throw new Error(`Target commit tracks .plans. See \`${ctx.forms.aligndev} guide work-files-setup\` for authorized preparation.`);
|
|
82
|
-
}
|
|
83
|
-
return {
|
|
84
|
-
".local": local,
|
|
85
|
-
".plans": { path: join(destination, ".plans"), mode: "symlink", target: plansTarget },
|
|
86
|
-
};
|
|
87
|
-
}
|
|
88
|
-
function planLocal(ctx, repo, destination, commit, warnings) {
|
|
89
|
-
const path = join(destination, ".local");
|
|
90
|
-
if (targetTracks(ctx, commit, ".local")) {
|
|
91
|
-
warnings.push("Target branch tracks .local; it remains branch-local and is not shared.");
|
|
92
|
-
return { path, mode: "tracked", target: null };
|
|
93
|
-
}
|
|
94
|
-
const source = join(repo.mainWorktree, ".local");
|
|
95
|
-
if (!pathExists(source))
|
|
96
|
-
return { path, mode: "absent", target: null };
|
|
97
|
-
if (!statSync(source).isDirectory())
|
|
98
|
-
throw new Error(`Source is not a usable directory: ${source}`);
|
|
99
|
-
const target = realpathSync(source);
|
|
100
|
-
if (isProjectTrackedDirectory(ctx, source, repo.commonDir)) {
|
|
101
|
-
warnings.push("Main-worktree .local belongs to tracked content on another branch; leaving .local absent.");
|
|
102
|
-
return { path, mode: "absent", target: null };
|
|
103
|
-
}
|
|
104
|
-
return { path, mode: "symlink", target };
|
|
105
|
-
}
|
|
106
|
-
function targetTracks(ctx, commit, path) {
|
|
107
|
-
return (git(ctx, "--literal-pathspecs", "ls-tree", "-r", "--name-only", "-z", commit, "--", path)
|
|
108
|
-
.length > 0);
|
|
109
|
-
}
|
|
110
70
|
function createGitWorktree(ctx, options, prepared) {
|
|
111
71
|
const { branch, destination } = prepared;
|
|
112
72
|
const createArgs = branch.create
|
|
@@ -119,57 +79,3 @@ function createGitWorktree(ctx, options, prepared) {
|
|
|
119
79
|
throw new Error(`Git worktree creation failed: ${errorMessage(error)}\nInspect ${destination} and branch ${options.branch} for partial effects before retrying. No rollback was attempted.`);
|
|
120
80
|
}
|
|
121
81
|
}
|
|
122
|
-
function finishSetup(ctx, repo, options, prepared) {
|
|
123
|
-
const { destination, directories, warnings } = prepared;
|
|
124
|
-
let step = "directory links and local Git exclusions";
|
|
125
|
-
try {
|
|
126
|
-
const targetCtx = { ...ctx, cwd: destination };
|
|
127
|
-
createLinks(targetCtx, repo, directories);
|
|
128
|
-
step = "effective work-files verification";
|
|
129
|
-
validateEffectivePlans(targetCtx);
|
|
130
|
-
const worktree = readRepository(targetCtx).worktrees.find((tree) => tree.path === destination);
|
|
131
|
-
if (worktree === undefined || worktree.branch !== options.branch) {
|
|
132
|
-
throw new Error("Created worktree does not have the requested branch in Git's registry.");
|
|
133
|
-
}
|
|
134
|
-
return { mainWorktree: repo.mainWorktree, worktree, directories, warnings };
|
|
135
|
-
}
|
|
136
|
-
catch (error) {
|
|
137
|
-
throw new Error(`Worktree setup failed during ${step}: ${errorMessage(error)}\n` +
|
|
138
|
-
`Retained worktree ${destination} and branch ${options.branch}. Inspect and repair the failed step manually, ` +
|
|
139
|
-
`or remove it with \`${ctx.forms.aligndev} worktree remove ${quotePath(destination)}\` after preserving any work. No rollback was attempted.`);
|
|
140
|
-
}
|
|
141
|
-
}
|
|
142
|
-
function quotePath(path) {
|
|
143
|
-
return `'${path.replaceAll("'", "'\\''")}'`;
|
|
144
|
-
}
|
|
145
|
-
function createLinks(ctx, repo, directories) {
|
|
146
|
-
const links = Object.entries(directories).filter(([, directory]) => directory.mode === "symlink");
|
|
147
|
-
if (links.length === 0)
|
|
148
|
-
return;
|
|
149
|
-
for (const [name, directory] of links) {
|
|
150
|
-
if (directory.target === null)
|
|
151
|
-
throw new Error("Missing symlink target.");
|
|
152
|
-
symlinkSync(join(repo.mainWorktree, name), directory.path, "dir");
|
|
153
|
-
}
|
|
154
|
-
const exclude = git({ ...ctx, cwd: repo.mainWorktree }, "rev-parse", "--path-format=absolute", "--git-path", "info/exclude").trim();
|
|
155
|
-
let content = pathExists(exclude) ? readFileSync(exclude, "utf8") : "";
|
|
156
|
-
for (const [name] of links) {
|
|
157
|
-
const pattern = `/${name}`;
|
|
158
|
-
if (!content.split(/\r?\n/u).includes(pattern)) {
|
|
159
|
-
mkdirSync(dirname(exclude), { recursive: true });
|
|
160
|
-
const addition = `${content.endsWith("\n") || content === "" ? "" : "\n"}${pattern}\n`;
|
|
161
|
-
appendFileSync(exclude, addition);
|
|
162
|
-
content += addition;
|
|
163
|
-
}
|
|
164
|
-
}
|
|
165
|
-
for (const [name, directory] of links) {
|
|
166
|
-
try {
|
|
167
|
-
git(ctx, "check-ignore", "-q", "--", name);
|
|
168
|
-
}
|
|
169
|
-
catch {
|
|
170
|
-
throw new Error(`Generated link ${directory.path} is not ignored. Inspect conflicting tracked ignore rules; they were not edited.`);
|
|
171
|
-
}
|
|
172
|
-
if (realpathSync(directory.path) !== directory.target)
|
|
173
|
-
throw new Error(`Link target changed: ${directory.path}`);
|
|
174
|
-
}
|
|
175
|
-
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import { type Repository, type Worktree } from "./git.js";
|
|
2
|
+
import type { WorktreeContext } from "./worktree-cli.js";
|
|
3
|
+
export interface DirectoryPreparation {
|
|
4
|
+
directories: Record<".local" | ".plans", DirectoryReport>;
|
|
5
|
+
warnings: string[];
|
|
6
|
+
}
|
|
7
|
+
export interface DirectoryReport {
|
|
8
|
+
path: string;
|
|
9
|
+
mode: "directory" | "symlink" | "tracked" | "companion" | "absent";
|
|
10
|
+
target: string | null;
|
|
11
|
+
}
|
|
12
|
+
export interface WorktreeReport extends DirectoryPreparation {
|
|
13
|
+
mainWorktree: string;
|
|
14
|
+
worktree: Worktree;
|
|
15
|
+
}
|
|
16
|
+
export declare function setupWorktree(ctx: WorktreeContext, repo: Repository, input?: string): WorktreeReport;
|
|
17
|
+
export declare function prepareDirectories(ctx: WorktreeContext, repo: Repository, destination: string, commit: string, includeIndex?: boolean): DirectoryPreparation;
|
|
18
|
+
export declare function finishSetup(ctx: WorktreeContext, repo: Repository, destination: string, prepared: DirectoryPreparation, expectedBranch?: string): WorktreeReport;
|
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
import { appendFileSync, lstatSync, mkdirSync, readFileSync, realpathSync, statSync, symlinkSync, } from "node:fs";
|
|
2
|
+
import { dirname, join, resolve } from "node:path";
|
|
3
|
+
import { errorMessage } from "../errors.js";
|
|
4
|
+
import { readReport, validateEffectivePlans } from "../project/plans.js";
|
|
5
|
+
import { canonicalPath, git, isProjectTrackedDirectory, pathExists, readRepository, } from "./git.js";
|
|
6
|
+
export function setupWorktree(ctx, repo, input) {
|
|
7
|
+
const worktree = selectWorktree(ctx, repo, input);
|
|
8
|
+
let prepared;
|
|
9
|
+
try {
|
|
10
|
+
if (worktree.main)
|
|
11
|
+
return reportMain(ctx, repo, worktree);
|
|
12
|
+
prepared = prepareDirectories(ctx, repo, worktree.path, "HEAD", true);
|
|
13
|
+
}
|
|
14
|
+
catch (error) {
|
|
15
|
+
throw setupFailure(ctx, worktree.path, "directory preparation", error);
|
|
16
|
+
}
|
|
17
|
+
return finishSetup(ctx, repo, worktree.path, prepared);
|
|
18
|
+
}
|
|
19
|
+
function selectWorktree(ctx, repo, input) {
|
|
20
|
+
const path = canonicalPath(input === undefined ? git(ctx, "rev-parse", "--show-toplevel").trim() : resolve(ctx.cwd, input));
|
|
21
|
+
const worktree = repo.worktrees.find((tree) => tree.path === path);
|
|
22
|
+
if (worktree === undefined || !worktree.exists || !pathExists(path)) {
|
|
23
|
+
throw new Error(`Setup requires an existing registered worktree root of this repository: ${path}`);
|
|
24
|
+
}
|
|
25
|
+
const targetCtx = { ...ctx, cwd: path };
|
|
26
|
+
const targetRepo = readRepository(targetCtx);
|
|
27
|
+
if (targetRepo.commonDir !== repo.commonDir ||
|
|
28
|
+
canonicalPath(git(targetCtx, "rev-parse", "--show-toplevel").trim()) !== path) {
|
|
29
|
+
throw new Error(`Setup requires an exact registered worktree root: ${path}`);
|
|
30
|
+
}
|
|
31
|
+
return worktree;
|
|
32
|
+
}
|
|
33
|
+
function reportMain(ctx, repo, worktree) {
|
|
34
|
+
const sourceCtx = { ...ctx, cwd: repo.mainWorktree };
|
|
35
|
+
const report = readReport(sourceCtx);
|
|
36
|
+
validateEffectivePlans(sourceCtx);
|
|
37
|
+
const plans = report.locations[".plans"];
|
|
38
|
+
return {
|
|
39
|
+
mainWorktree: repo.mainWorktree,
|
|
40
|
+
worktree,
|
|
41
|
+
directories: {
|
|
42
|
+
".local": describeDirectory(join(repo.mainWorktree, ".local")),
|
|
43
|
+
".plans": plans.in === "companion"
|
|
44
|
+
? { path: plans.path, mode: "companion", target: null }
|
|
45
|
+
: describeDirectory(plans.path),
|
|
46
|
+
},
|
|
47
|
+
warnings: [],
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
function describeDirectory(path) {
|
|
51
|
+
if (!pathExists(path))
|
|
52
|
+
return { path, mode: "absent", target: null };
|
|
53
|
+
if (!statSync(path).isDirectory())
|
|
54
|
+
throw new Error(`Source is not a usable directory: ${path}`);
|
|
55
|
+
return lstatSync(path).isSymbolicLink()
|
|
56
|
+
? { path, mode: "symlink", target: realpathSync(path) }
|
|
57
|
+
: { path, mode: "directory", target: null };
|
|
58
|
+
}
|
|
59
|
+
export function prepareDirectories(ctx, repo, destination, commit, includeIndex = false) {
|
|
60
|
+
const sourceCtx = { ...ctx, cwd: repo.mainWorktree };
|
|
61
|
+
const report = readReport(sourceCtx);
|
|
62
|
+
const plansTarget = validateEffectivePlans(sourceCtx);
|
|
63
|
+
const targetCtx = includeIndex ? { ...ctx, cwd: destination } : sourceCtx;
|
|
64
|
+
const warnings = [];
|
|
65
|
+
const local = planLocal(sourceCtx, targetCtx, repo, destination, commit, includeIndex, warnings);
|
|
66
|
+
const plans = report.locations[".plans"];
|
|
67
|
+
if (plans.in === "companion") {
|
|
68
|
+
return {
|
|
69
|
+
directories: {
|
|
70
|
+
".local": local,
|
|
71
|
+
".plans": { path: plans.path, mode: "companion", target: null },
|
|
72
|
+
},
|
|
73
|
+
warnings,
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
if (targetTracks(targetCtx, commit, ".plans", includeIndex)) {
|
|
77
|
+
throw new Error(`Target commit${includeIndex ? " or index" : ""} tracks .plans. See the \`work-files-setup\` topic of \`${ctx.forms.aligndev} guide\` for authorized preparation.`);
|
|
78
|
+
}
|
|
79
|
+
return {
|
|
80
|
+
directories: {
|
|
81
|
+
".local": local,
|
|
82
|
+
".plans": { path: join(destination, ".plans"), mode: "symlink", target: plansTarget },
|
|
83
|
+
},
|
|
84
|
+
warnings,
|
|
85
|
+
};
|
|
86
|
+
}
|
|
87
|
+
function planLocal(sourceCtx, targetCtx, repo, destination, commit, includeIndex, warnings) {
|
|
88
|
+
const path = join(destination, ".local");
|
|
89
|
+
if (targetTracks(targetCtx, commit, ".local", includeIndex)) {
|
|
90
|
+
warnings.push("Target branch tracks .local; it remains branch-local and is not shared.");
|
|
91
|
+
return { path, mode: "tracked", target: null };
|
|
92
|
+
}
|
|
93
|
+
const source = join(repo.mainWorktree, ".local");
|
|
94
|
+
if (!pathExists(source))
|
|
95
|
+
return { path, mode: "absent", target: null };
|
|
96
|
+
if (!statSync(source).isDirectory())
|
|
97
|
+
throw new Error(`Source is not a usable directory: ${source}`);
|
|
98
|
+
const target = realpathSync(source);
|
|
99
|
+
if (isProjectTrackedDirectory(sourceCtx, source, repo.commonDir)) {
|
|
100
|
+
warnings.push("Main-worktree .local belongs to tracked content on another branch; leaving .local absent.");
|
|
101
|
+
return { path, mode: "absent", target: null };
|
|
102
|
+
}
|
|
103
|
+
return { path, mode: "symlink", target };
|
|
104
|
+
}
|
|
105
|
+
function targetTracks(ctx, commit, path, includeIndex) {
|
|
106
|
+
return (git(ctx, "--literal-pathspecs", "ls-tree", "-r", "--name-only", "-z", commit, "--", path)
|
|
107
|
+
.length > 0 ||
|
|
108
|
+
(includeIndex && git(ctx, "--literal-pathspecs", "ls-files", "-z", "--", path).length > 0));
|
|
109
|
+
}
|
|
110
|
+
export function finishSetup(ctx, repo, destination, prepared, expectedBranch) {
|
|
111
|
+
let step = "directory conflict checks";
|
|
112
|
+
try {
|
|
113
|
+
const targetCtx = { ...ctx, cwd: destination };
|
|
114
|
+
checkDestinations(prepared.directories);
|
|
115
|
+
step = "directory links and local Git exclusions";
|
|
116
|
+
applyDirectories(targetCtx, repo, prepared.directories);
|
|
117
|
+
step = "effective work-files verification";
|
|
118
|
+
validateEffectivePlans(targetCtx);
|
|
119
|
+
const worktree = readRepository(targetCtx).worktrees.find((tree) => tree.path === destination);
|
|
120
|
+
if (worktree === undefined ||
|
|
121
|
+
(expectedBranch !== undefined && worktree.branch !== expectedBranch)) {
|
|
122
|
+
throw new Error("Worktree does not have the requested branch in Git's registry.");
|
|
123
|
+
}
|
|
124
|
+
return { mainWorktree: repo.mainWorktree, worktree, ...prepared };
|
|
125
|
+
}
|
|
126
|
+
catch (error) {
|
|
127
|
+
throw setupFailure(ctx, destination, step, error, expectedBranch);
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
function checkDestinations(directories) {
|
|
131
|
+
for (const directory of Object.values(directories)) {
|
|
132
|
+
if (directory.mode !== "symlink")
|
|
133
|
+
continue;
|
|
134
|
+
if (directory.target === null)
|
|
135
|
+
throw new Error("Missing symlink target.");
|
|
136
|
+
if (!pathExists(directory.path))
|
|
137
|
+
continue;
|
|
138
|
+
if (lstatSync(directory.path).isSymbolicLink()) {
|
|
139
|
+
try {
|
|
140
|
+
if (realpathSync(directory.path) === directory.target)
|
|
141
|
+
continue;
|
|
142
|
+
}
|
|
143
|
+
catch {
|
|
144
|
+
// Broken and cyclic links are conflicts, not missing destinations.
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
throw new Error(`Conflicting shared directory destination: ${directory.path}. Existing content was preserved.`);
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
function applyDirectories(ctx, repo, directories) {
|
|
151
|
+
const links = Object.entries(directories).filter(([, directory]) => directory.mode === "symlink");
|
|
152
|
+
if (links.length === 0)
|
|
153
|
+
return;
|
|
154
|
+
for (const [name, directory] of links) {
|
|
155
|
+
if (!pathExists(directory.path))
|
|
156
|
+
symlinkSync(join(repo.mainWorktree, name), directory.path, "dir");
|
|
157
|
+
}
|
|
158
|
+
ensureExclusions(ctx, repo, links.map(([name]) => name));
|
|
159
|
+
for (const [name, directory] of links) {
|
|
160
|
+
try {
|
|
161
|
+
git(ctx, "check-ignore", "-q", "--", name);
|
|
162
|
+
}
|
|
163
|
+
catch {
|
|
164
|
+
throw new Error(`Generated link ${directory.path} is not ignored. Inspect conflicting tracked ignore rules; they were not edited.`);
|
|
165
|
+
}
|
|
166
|
+
if (realpathSync(directory.path) !== directory.target)
|
|
167
|
+
throw new Error(`Link target changed: ${directory.path}`);
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
function ensureExclusions(ctx, repo, names) {
|
|
171
|
+
const exclude = git({ ...ctx, cwd: repo.mainWorktree }, "rev-parse", "--path-format=absolute", "--git-path", "info/exclude").trim();
|
|
172
|
+
let content = pathExists(exclude) ? readFileSync(exclude, "utf8") : "";
|
|
173
|
+
for (const name of names) {
|
|
174
|
+
const pattern = `/${name}`;
|
|
175
|
+
if (content.split(/\r?\n/u).includes(pattern))
|
|
176
|
+
continue;
|
|
177
|
+
mkdirSync(dirname(exclude), { recursive: true });
|
|
178
|
+
const addition = `${content.endsWith("\n") || content === "" ? "" : "\n"}${pattern}\n`;
|
|
179
|
+
appendFileSync(exclude, addition);
|
|
180
|
+
content += addition;
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
function setupFailure(ctx, destination, step, error, branch) {
|
|
184
|
+
const quoted = `'${destination.replaceAll("'", "'\\''")}'`;
|
|
185
|
+
return new Error(`Worktree setup failed during ${step}: ${errorMessage(error)}\n` +
|
|
186
|
+
`Retained worktree ${destination}${branch === undefined ? " and its Git state" : ` and branch ${branch}`}. ` +
|
|
187
|
+
`Inspect and repair the failed step manually, then retry with \`${ctx.forms.aligndev} worktree setup ${quoted}\`.` +
|
|
188
|
+
(branch === undefined
|
|
189
|
+
? ""
|
|
190
|
+
: ` Or remove it with \`${ctx.forms.aligndev} worktree remove ${quoted}\` after preserving any work.`) +
|
|
191
|
+
" No rollback was attempted.");
|
|
192
|
+
}
|
|
@@ -2,6 +2,7 @@ import { parseArgs } from "node:util";
|
|
|
2
2
|
import { addWorktree } from "./add.js";
|
|
3
3
|
import { readRepository } from "./git.js";
|
|
4
4
|
import { removeWorktree } from "./remove.js";
|
|
5
|
+
import { setupWorktree } from "./setup.js";
|
|
5
6
|
export function runWorktree(tokens, ctx) {
|
|
6
7
|
const command = parseWorktreeArgs(tokens, ctx.forms.aligndev);
|
|
7
8
|
if (command.kind === "help") {
|
|
@@ -19,10 +20,12 @@ export function runWorktree(tokens, ctx) {
|
|
|
19
20
|
ctx.stdout.write(command.json ? json(report) : `Removed ${report.path}; branch preserved.\n`);
|
|
20
21
|
return 0;
|
|
21
22
|
}
|
|
22
|
-
const report =
|
|
23
|
+
const report = command.kind === "setup"
|
|
24
|
+
? setupWorktree(ctx, repo, command.path)
|
|
25
|
+
: addWorktree(ctx, repo, command.options);
|
|
23
26
|
for (const warning of report.warnings)
|
|
24
27
|
ctx.stderr.write(`Warning: ${warning}\n`);
|
|
25
|
-
ctx.stdout.write(command.json ? json(report) :
|
|
28
|
+
ctx.stdout.write(command.json ? json(report) : renderReady(report));
|
|
26
29
|
return 0;
|
|
27
30
|
}
|
|
28
31
|
function parseWorktreeArgs(tokens, aligndev) {
|
|
@@ -32,7 +35,7 @@ function parseWorktreeArgs(tokens, aligndev) {
|
|
|
32
35
|
throw new Error("Unexpected worktree help arguments.");
|
|
33
36
|
return { kind: "help" };
|
|
34
37
|
}
|
|
35
|
-
if (command !== "add" && command !== "list" && command !== "remove") {
|
|
38
|
+
if (command !== "add" && command !== "setup" && command !== "list" && command !== "remove") {
|
|
36
39
|
throw new Error(`Unknown worktree command: ${command}`);
|
|
37
40
|
}
|
|
38
41
|
const { values, positionals } = parseArgs({
|
|
@@ -50,12 +53,18 @@ function parseWorktreeArgs(tokens, aligndev) {
|
|
|
50
53
|
const newBranch = typeof values.b === "string" ? values.b : undefined;
|
|
51
54
|
const count = positionals.length;
|
|
52
55
|
const expected = command === "list" ? 0 : command === "remove" ? 1 : 2;
|
|
53
|
-
const validCount = command === "
|
|
56
|
+
const validCount = command === "setup"
|
|
57
|
+
? count <= 1
|
|
58
|
+
: command === "add" && newBranch !== undefined
|
|
59
|
+
? count === 1 || count === 2
|
|
60
|
+
: count === expected;
|
|
54
61
|
if (!validCount) {
|
|
55
62
|
throw new Error(`Invalid arguments. Run \`${aligndev} worktree ${command} --help\`.`);
|
|
56
63
|
}
|
|
57
64
|
if (command === "list")
|
|
58
65
|
return { kind: "list", json: values.json };
|
|
66
|
+
if (command === "setup")
|
|
67
|
+
return { kind: "setup", path: positionals[0], json: values.json };
|
|
59
68
|
const path = positionals[0];
|
|
60
69
|
if (path === undefined)
|
|
61
70
|
throw new Error("A worktree path is required.");
|
|
@@ -83,9 +92,9 @@ function renderList(worktrees) {
|
|
|
83
92
|
.map((tree) => `${tree.path} [${tree.branch ?? "detached"}]${tree.main ? " main" : ""}${tree.exists ? "" : " missing"}${tree.locked ? " locked" : ""}${tree.prunable ? " prunable" : ""}\n`)
|
|
84
93
|
.join("");
|
|
85
94
|
}
|
|
86
|
-
function
|
|
95
|
+
function renderReady(report) {
|
|
87
96
|
return [
|
|
88
|
-
`Worktree ready: ${report.worktree.path} [${report.worktree.branch}]`,
|
|
97
|
+
`Worktree ready: ${report.worktree.path} [${report.worktree.branch ?? "detached"}]`,
|
|
89
98
|
...Object.entries(report.directories).map(([name, directory]) => `${name}: ${directory.mode} ${directory.path}${directory.target === null ? "" : ` -> ${directory.target}`}`),
|
|
90
99
|
"Readiness covers Git and work files only; follow the project's install/build/test procedure.",
|
|
91
100
|
"",
|
|
@@ -95,6 +104,7 @@ function renderHelp(command) {
|
|
|
95
104
|
return `Usage:
|
|
96
105
|
${command} worktree add <path> <branch> [--json]
|
|
97
106
|
${command} worktree add <path> -b <branch> [<start-point>] [--json]
|
|
107
|
+
${command} worktree setup [<path>] [--json]
|
|
98
108
|
${command} worktree list [--json]
|
|
99
109
|
${command} worktree remove <path> [--json]
|
|
100
110
|
${command} worktree <command> --help
|
|
@@ -105,12 +115,20 @@ Existing branches are reused; an unambiguous fetched remote branch may create it
|
|
|
105
115
|
The destination must be new and outside all registered worktrees. Occupied branches must be reused
|
|
106
116
|
at their listed path. Bare and nonstandard Git layouts are unsupported.
|
|
107
117
|
|
|
108
|
-
Add
|
|
118
|
+
Add and setup share usable untracked main-worktree .plans and optional .local through symlinks, with local
|
|
109
119
|
Git exclusions. Companion plans are used directly. Tracked .local stays branch-local with a warning.
|
|
110
|
-
Missing or project-tracked effective plans require separately authorized preparation:
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
120
|
+
Missing or project-tracked effective plans require separately authorized preparation: see the
|
|
121
|
+
work-files-setup topic of ${command} guide.
|
|
122
|
+
Neither command registers a companion, migrates files, installs, builds or starts application processes.
|
|
123
|
+
Readiness covers Git and work files only; follow repository preparation and shutdown separately.
|
|
124
|
+
Setup without a path discovers the current Git worktree root, including from a nested directory.
|
|
125
|
+
An explicit path must be an exact existing registered root of this repository; main and detached
|
|
126
|
+
worktrees are supported. Setup preserves branches, the index, unrelated files and Git registration.
|
|
127
|
+
Equivalent shared links are reused. Conflicts are preserved; repair them and retry idempotent setup.
|
|
128
|
+
Late failures retain partial preparation and report a quoted setup retry command.
|
|
129
|
+
External tools may use this post-creation hook inside their worktree:
|
|
130
|
+
${command} worktree setup
|
|
131
|
+
There is no lightweight teardown hook; the external owner manages deletion and project shutdown.
|
|
114
132
|
|
|
115
133
|
List reads only Git's registry, including detached, missing, locked and prunable worktrees.
|
|
116
134
|
Remove accepts an exact linked root, refuses main/locked/dirty/protected shared targets, and uses
|