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.
Files changed (37) hide show
  1. package/README.md +13 -5
  2. package/dist/alignfirst-cli.js +21 -8
  3. package/dist/cli.d.ts +2 -0
  4. package/dist/cli.js +16 -4
  5. package/dist/code/claude-agent.js +1 -1
  6. package/dist/code/code-cli.js +2 -4
  7. package/dist/code/codex-agent.js +1 -1
  8. package/dist/code/machine-id.js +14 -3
  9. package/dist/code/pi-agent.js +1 -1
  10. package/dist/code/run-agent.js +37 -1
  11. package/dist/command-form.d.ts +5 -2
  12. package/dist/command-form.js +15 -6
  13. package/dist/guide/code-guide.d.ts +2 -2
  14. package/dist/guide/code-guide.js +4 -8
  15. package/dist/guide/guide-cli.js +84 -29
  16. package/dist/guide/render-template.d.ts +4 -0
  17. package/dist/guide/render-template.js +51 -12
  18. package/dist/guide/topics.d.ts +8 -3
  19. package/dist/guide/topics.js +26 -7
  20. package/dist/project/plans.js +1 -1
  21. package/dist/worktree/add.d.ts +3 -13
  22. package/dist/worktree/add.js +7 -101
  23. package/dist/worktree/setup.d.ts +18 -0
  24. package/dist/worktree/setup.js +192 -0
  25. package/dist/worktree/worktree-cli.js +29 -11
  26. package/package.json +4 -1
  27. package/templates/guide/code.md +12 -3
  28. package/templates/guide/playbook/channel-handling.md +12 -17
  29. package/templates/guide/playbook/consultation.md +24 -17
  30. package/templates/guide/playbook/dispatcher.md +18 -0
  31. package/templates/guide/playbook/{discord-message-tool.md → message-tool.md} +29 -0
  32. package/templates/guide/playbook/playbook.md +53 -20
  33. package/templates/guide/playbook/project-lifecycle.md +26 -11
  34. package/templates/guide/playbook/project-workspace-setup.md +87 -62
  35. package/templates/guide/playbook/work-files-setup.md +1 -1
  36. package/templates/guide/playbook/working-session.md +195 -112
  37. 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
- // A block is `{{#<name>}}` … `{{/<name>}}`, each marker alone on its line. A platform block sits
22
- // at the top level; a condition block sits directly inside a `codingAgent` block. A line
23
- // is kept when every block around it is active. The runs of empty lines that removed blocks leave
24
- // collapse to one.
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 outer = open.at(-1);
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 (outer?.name !== "codingAgent") {
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 (!isPlatform(name) && !isCondition(name)) {
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
  }
@@ -1,3 +1,8 @@
1
- import type { Platform } from "../config.js";
2
- export declare const PLAYBOOK_DISPATCHER = "playbook";
3
- export declare const PLAYBOOK_TOPICS: Record<Platform, readonly string[]>;
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[];
@@ -1,17 +1,36 @@
1
- // The template rendered by `aligndev guide` without a topic.
2
- export const PLAYBOOK_DISPATCHER = "playbook";
3
- // The playbook topics each platform serves. Every topic is one file of `templates/guide/playbook/`,
4
- // shared by the platforms through platform blocks.
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
- openclaw: [
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
- "slack-message-tool",
14
- "discord-message-tool",
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
+ }
@@ -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 work-files-setup\` for authorized preparation.`);
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) {
@@ -1,4 +1,5 @@
1
- import { type Repository, type Worktree } from "./git.js";
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 interface AddReport {
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;
@@ -1,22 +1,18 @@
1
- import { appendFileSync, mkdirSync, readFileSync, realpathSync, statSync, symlinkSync, } from "node:fs";
2
- import { dirname, join, resolve } from "node:path";
1
+ import { statSync } from "node:fs";
2
+ import { dirname, resolve } from "node:path";
3
3
  import { errorMessage } from "../errors.js";
4
- import { readReport, validateEffectivePlans } from "../project/plans.js";
5
- import { canonicalPath, git, isInside, isProjectTrackedDirectory, pathExists, readRepository, } from "./git.js";
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, options, prepared);
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 sourceCtx = { ...ctx, cwd: repo.mainWorktree };
15
- const sourceReport = readReport(sourceCtx);
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 = addWorktree(ctx, repo, command.options);
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) : renderAdd(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 === "add" && newBranch !== undefined ? count === 1 || count === 2 : count === expected;
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 renderAdd(report) {
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 shares usable untracked main-worktree .plans and optional .local through symlinks, with local
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
- ${command} guide work-files-setup
112
- Add never registers a companion, migrates files, installs, builds or starts application processes.
113
- Late setup failures retain the worktree and branch and report manual recovery.
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