aligndev 0.28.1 → 0.30.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 +16 -6
- package/dist/alignfirst-cli.js +22 -10
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +14 -12
- package/dist/code/claude-agent.js +1 -1
- package/dist/code/code-cli.js +3 -5
- 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 +82 -30
- package/dist/guide/render-template.d.ts +4 -4
- package/dist/guide/render-template.js +42 -21
- package/dist/guide/topics.d.ts +8 -3
- package/dist/guide/topics.js +26 -7
- package/dist/project/discovery.js +5 -12
- package/dist/project/layout.d.ts +22 -9
- package/dist/project/layout.js +101 -28
- package/dist/project/plans.d.ts +1 -1
- package/dist/project/plans.js +1 -1
- package/dist/project/render.js +3 -1
- package/dist/project/status.d.ts +2 -2
- package/dist/project/status.js +2 -2
- package/package.json +5 -1
- package/templates/guide/code.md +12 -3
- package/templates/guide/playbook/channel-handling.md +12 -17
- package/templates/guide/playbook/consultation.md +27 -30
- 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 +55 -25
- package/templates/guide/playbook/project-lifecycle.md +33 -18
- package/templates/guide/playbook/project-workspace-setup.md +91 -71
- package/templates/guide/playbook/work-files-setup.md +2 -2
- package/templates/guide/playbook/working-session.md +207 -158
- package/templates/guide/project.md +4 -4
- package/dist/guide/guide-file.d.ts +0 -3
- package/dist/guide/guide-file.js +0 -26
- package/dist/worktree/add.d.ts +0 -20
- package/dist/worktree/add.js +0 -175
- package/dist/worktree/git.d.ts +0 -24
- package/dist/worktree/git.js +0 -103
- package/dist/worktree/remove.d.ts +0 -8
- package/dist/worktree/remove.js +0 -62
- package/dist/worktree/worktree-cli.d.ts +0 -10
- package/dist/worktree/worktree-cli.js +0 -122
- package/templates/guide/playbook/slack-message-tool.md +0 -23
|
@@ -1,27 +1,40 @@
|
|
|
1
1
|
import { PLATFORMS } from "../config.js";
|
|
2
2
|
import { readTemplate } from "../templates.js";
|
|
3
|
-
const
|
|
4
|
-
//
|
|
5
|
-
|
|
3
|
+
export const SURFACES = ["slack", "discord", "app"];
|
|
4
|
+
// Derived facts: `thread` holds on Slack and Discord; `conversation` in an app conversation and
|
|
5
|
+
// under codingAgent.
|
|
6
|
+
const THREAD = "thread";
|
|
7
|
+
const CONVERSATION = "conversation";
|
|
6
8
|
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`.
|
|
9
|
+
// Renders `templates/guide/<name>`: the blocks first, then the placeholders — the command forms,
|
|
10
|
+
// the guide command of the render, and every key of `values`.
|
|
9
11
|
export function renderGuideTemplate(name, active, forms, values = {}) {
|
|
10
12
|
const placeholders = {
|
|
11
13
|
ALIGNDEV: forms.aligndev,
|
|
12
14
|
ALIGNFIRST: forms.alignfirst,
|
|
15
|
+
...guidePlaceholder(active, forms),
|
|
16
|
+
BACKGROUND_COMMAND_JSON: JSON.stringify(`${forms.aligndev} code new --message-file '/tmp/aligndev-request.txt' --quiet --meta 'a20bc7c1-c056-4d07-8cc2-90fe491a6df6'`),
|
|
13
17
|
...values,
|
|
14
18
|
};
|
|
15
19
|
let text = renderBlocks(readTemplate(`guide/${name}`), active, name);
|
|
16
20
|
for (const [key, value] of Object.entries(placeholders)) {
|
|
17
|
-
text = text.replaceAll(`{{${key}}}`, value);
|
|
21
|
+
text = text.replaceAll(`{{${key}}}`, () => value);
|
|
18
22
|
}
|
|
19
23
|
return text.trimEnd();
|
|
20
24
|
}
|
|
21
|
-
//
|
|
22
|
-
//
|
|
23
|
-
|
|
24
|
-
|
|
25
|
+
// `{{GUIDE}}` carries the surface into every later guide call. An OpenClaw render without a surface
|
|
26
|
+
// has none.
|
|
27
|
+
function guidePlaceholder(active, forms) {
|
|
28
|
+
if (active.surface !== undefined) {
|
|
29
|
+
return { GUIDE: `${forms.aligndev} guide --channel ${active.surface}` };
|
|
30
|
+
}
|
|
31
|
+
return active.platform === "codingAgent" ? { GUIDE: `${forms.aligndev} guide` } : {};
|
|
32
|
+
}
|
|
33
|
+
// A block is `{{#<name>}}` … `{{/<name>}}`, each marker alone on its line, and names a fact. A
|
|
34
|
+
// platform block sits at the top level. A surface block and `thread` never sit inside a
|
|
35
|
+
// `codingAgent` block; `conversation` sits anywhere.
|
|
36
|
+
// A line is kept when every block around it holds. The runs of empty lines that removed blocks
|
|
37
|
+
// leave collapse to one.
|
|
25
38
|
export function renderBlocks(text, active, templateName) {
|
|
26
39
|
const kept = [];
|
|
27
40
|
const open = [];
|
|
@@ -46,40 +59,48 @@ export function renderBlocks(text, active, templateName) {
|
|
|
46
59
|
return collapseEmptyLines(kept).join("\n");
|
|
47
60
|
}
|
|
48
61
|
function isActive(name, active) {
|
|
49
|
-
if (name ===
|
|
50
|
-
return active.
|
|
51
|
-
|
|
62
|
+
if (name === THREAD)
|
|
63
|
+
return active.surface === "slack" || active.surface === "discord";
|
|
64
|
+
if (name === CONVERSATION)
|
|
65
|
+
return active.surface === "app" || active.platform === "codingAgent";
|
|
66
|
+
return name === active.platform || name === active.surface;
|
|
52
67
|
}
|
|
53
68
|
function openBlock(name, line, open, templateName) {
|
|
54
|
-
const
|
|
69
|
+
const insideCodingAgent = open.some((block) => block.name === "codingAgent");
|
|
55
70
|
if (isPlatform(name)) {
|
|
71
|
+
const outer = open.at(-1);
|
|
56
72
|
if (outer !== undefined) {
|
|
57
73
|
throw blockError(templateName, line, `platform block "${name}" inside "${outer.name}"`);
|
|
58
74
|
}
|
|
59
75
|
return { name, line };
|
|
60
76
|
}
|
|
61
|
-
if (
|
|
62
|
-
if (
|
|
63
|
-
|
|
77
|
+
if (isSurface(name) || name === THREAD) {
|
|
78
|
+
if (insideCodingAgent) {
|
|
79
|
+
const block = isSurface(name) ? `surface block "${name}"` : `block "${name}"`;
|
|
80
|
+
throw blockError(templateName, line, `${block} inside a codingAgent block`);
|
|
64
81
|
}
|
|
65
82
|
return { name, line };
|
|
66
83
|
}
|
|
84
|
+
if (name === CONVERSATION)
|
|
85
|
+
return { name, line };
|
|
67
86
|
throw blockError(templateName, line, `unknown block "${name}"`);
|
|
68
87
|
}
|
|
69
88
|
function closeBlock(name, line, open, templateName) {
|
|
70
|
-
if (!
|
|
89
|
+
if (!isBlockName(name))
|
|
71
90
|
throw blockError(templateName, line, `unknown block "${name}"`);
|
|
72
|
-
}
|
|
73
91
|
if (open.at(-1)?.name !== name) {
|
|
74
92
|
throw blockError(templateName, line, `closing marker "${name}" without its block`);
|
|
75
93
|
}
|
|
76
94
|
open.pop();
|
|
77
95
|
}
|
|
96
|
+
function isBlockName(name) {
|
|
97
|
+
return isPlatform(name) || isSurface(name) || name === THREAD || name === CONVERSATION;
|
|
98
|
+
}
|
|
78
99
|
function isPlatform(name) {
|
|
79
100
|
return PLATFORMS.includes(name);
|
|
80
101
|
}
|
|
81
|
-
function
|
|
82
|
-
return
|
|
102
|
+
export function isSurface(name) {
|
|
103
|
+
return SURFACES.includes(name);
|
|
83
104
|
}
|
|
84
105
|
function blockError(templateName, line, detail) {
|
|
85
106
|
return new Error(`Error: template ${templateName}, line ${line}: ${detail}.`);
|
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
|
+
}
|
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
|
|
2
2
|
import { basename, dirname, join, resolve, sep } from "node:path";
|
|
3
3
|
import { isNodeError } from "../errors.js";
|
|
4
4
|
import { formatRange } from "./format.js";
|
|
5
5
|
import { readProjectReport } from "./layout.js";
|
|
6
6
|
import { containsRange, rangesOverlap, readMarker, } from "./markers.js";
|
|
7
|
-
const
|
|
7
|
+
const CONFIG_FILENAMES = ["alignfirst.json", "alignfirst.jsonc"];
|
|
8
8
|
export function buildInventory(root, marker, ctx) {
|
|
9
9
|
const state = { directories: [], candidates: [], directoryClaims: [], issues: [] };
|
|
10
10
|
walkProjectsDirectory(root, marker, undefined, state);
|
|
@@ -68,7 +68,7 @@ function classifyCandidates(state, ctx) {
|
|
|
68
68
|
}
|
|
69
69
|
function classifyCandidate(candidate, state, ctx) {
|
|
70
70
|
if (mainWorktreeGitDirectory(candidate.path) === undefined) {
|
|
71
|
-
if (
|
|
71
|
+
if (CONFIG_FILENAMES.some((name) => lstatSync(join(candidate.path, name), { throwIfNoEntry: false }) !== undefined)) {
|
|
72
72
|
state.issues.push({ path: candidate.path, message: "not a git main worktree" });
|
|
73
73
|
}
|
|
74
74
|
else {
|
|
@@ -86,21 +86,14 @@ function classifyCandidate(candidate, state, ctx) {
|
|
|
86
86
|
path: candidate.path,
|
|
87
87
|
directory: candidate.directory,
|
|
88
88
|
description,
|
|
89
|
-
...(description.
|
|
89
|
+
...(description.workspace.portRange === null
|
|
90
90
|
? {}
|
|
91
|
-
: { portRange: description.
|
|
91
|
+
: { portRange: description.workspace.portRange }),
|
|
92
92
|
workspaces: [],
|
|
93
93
|
};
|
|
94
94
|
const enclosingRange = findEnclosingRange(candidate.enclosingRanges, project.portRange);
|
|
95
95
|
if (enclosingRange?.code !== undefined)
|
|
96
96
|
project.portRangeCode = enclosingRange.code;
|
|
97
|
-
if (description.cli !== null && !description.cli.satisfied) {
|
|
98
|
-
state.issues.push({
|
|
99
|
-
path: candidate.path,
|
|
100
|
-
message: `AlignFirst CLI ${description.cli.installed} does not satisfy required range ` +
|
|
101
|
-
description.cli.range,
|
|
102
|
-
});
|
|
103
|
-
}
|
|
104
97
|
reportOutsideRange(project.path, project.portRange, candidate.enclosingRanges, state.issues);
|
|
105
98
|
return [project];
|
|
106
99
|
}
|
package/dist/project/layout.d.ts
CHANGED
|
@@ -1,33 +1,46 @@
|
|
|
1
1
|
import type { PortRange } from "./markers.js";
|
|
2
|
-
export type ItemName = "
|
|
2
|
+
export type ItemName = "alignfirst" | ".alignfirst-instructions" | "developerInstructions" | "workspaceRuntime" | "docs" | ".plans" | "_aligndev";
|
|
3
3
|
export interface ProjectReport {
|
|
4
4
|
source: ConfigSource | null;
|
|
5
|
-
|
|
5
|
+
workspace: WorkspaceConfigReport;
|
|
6
6
|
config: ProjectConfigView | null;
|
|
7
7
|
companion: CompanionReport | null;
|
|
8
8
|
aligndev: AligndevProjectSettings | null;
|
|
9
|
-
locations:
|
|
9
|
+
locations: ProjectLocations;
|
|
10
|
+
selectionOrigins: Record<ItemName, SelectionOrigin>;
|
|
10
11
|
}
|
|
12
|
+
export type SelectionOrigin = "item" | "defaultLocation" | "builtin";
|
|
13
|
+
export type ProjectLocations = Record<Exclude<ItemName, "developerInstructions">, ItemLocation> & {
|
|
14
|
+
developerInstructions: ItemLocation | null;
|
|
15
|
+
};
|
|
11
16
|
export interface AligndevProjectSettings {
|
|
12
17
|
profile: string;
|
|
13
18
|
}
|
|
14
19
|
export type ConfigSource = "project" | "companion";
|
|
15
|
-
export interface
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
20
|
+
export interface WorkspaceConfigReport {
|
|
21
|
+
location: ItemLocation;
|
|
22
|
+
registryDir: string;
|
|
23
|
+
runtimeDir: string;
|
|
24
|
+
schemaVersion: number | null;
|
|
25
|
+
portRange: PortRange | null;
|
|
26
|
+
hasDevServer: boolean;
|
|
19
27
|
}
|
|
20
28
|
export interface ProjectConfigView {
|
|
21
|
-
|
|
29
|
+
conventions?: {
|
|
30
|
+
ticketIdPattern?: string;
|
|
31
|
+
};
|
|
32
|
+
developerInstructions?: string;
|
|
22
33
|
plans?: {
|
|
23
34
|
repositoryFolder?: string;
|
|
24
35
|
};
|
|
25
|
-
portRange?: PortRange;
|
|
26
36
|
}
|
|
27
37
|
export interface CompanionReport {
|
|
28
38
|
dir: string;
|
|
29
39
|
exists: boolean;
|
|
40
|
+
defaultLocation: "project" | "companion" | "auto";
|
|
41
|
+
items: Record<ItemName, ItemSetting>;
|
|
30
42
|
}
|
|
43
|
+
export type ItemSetting = "project" | "companion" | "auto";
|
|
31
44
|
export interface ItemLocation {
|
|
32
45
|
path: string;
|
|
33
46
|
in: "project" | "companion";
|
package/dist/project/layout.js
CHANGED
|
@@ -30,22 +30,32 @@ function firstLine(value) {
|
|
|
30
30
|
function isOutdatedReport(value) {
|
|
31
31
|
return (isRecord(value) &&
|
|
32
32
|
(!Object.hasOwn(value, "aligndev") ||
|
|
33
|
-
!(
|
|
33
|
+
!Object.hasOwn(value, "workspace") ||
|
|
34
|
+
!Object.hasOwn(value, "selectionOrigins") ||
|
|
35
|
+
!(isRecord(value.locations) &&
|
|
36
|
+
"alignfirst" in value.locations &&
|
|
37
|
+
".alignfirst-instructions" in value.locations &&
|
|
38
|
+
"developerInstructions" in value.locations &&
|
|
39
|
+
"workspaceRuntime" in value.locations &&
|
|
40
|
+
isRecord(value.workspace) &&
|
|
41
|
+
"registryDir" in value.workspace &&
|
|
42
|
+
"runtimeDir" in value.workspace)));
|
|
34
43
|
}
|
|
35
44
|
function outdatedAlignfirst(path) {
|
|
36
|
-
return (`The alignfirst CLI used in ${path} is too old: aligndev requires the
|
|
37
|
-
|
|
45
|
+
return (`The alignfirst CLI used in ${path} is too old: aligndev requires the workspace-aware ` +
|
|
46
|
+
"alignfirst config --json contract (merged configuration, developerInstructions, workspaceRuntime and selectionOrigins). Upgrade alignfirst.");
|
|
38
47
|
}
|
|
39
48
|
function parseProjectReport(value, path) {
|
|
40
49
|
if (!isRecord(value))
|
|
41
50
|
throw invalidReport(path);
|
|
42
51
|
return {
|
|
43
52
|
source: parseSource(value.source, path),
|
|
44
|
-
|
|
53
|
+
workspace: parseWorkspace(value.workspace, path),
|
|
45
54
|
config: parseConfig(value.config, path),
|
|
46
55
|
companion: parseCompanion(value.companion, path),
|
|
47
56
|
aligndev: parseAligndev(value.aligndev, path),
|
|
48
57
|
locations: parseLocations(value.locations, path),
|
|
58
|
+
selectionOrigins: parseSelectionOrigins(value.selectionOrigins, path),
|
|
49
59
|
};
|
|
50
60
|
}
|
|
51
61
|
function parseAligndev(value, path) {
|
|
@@ -63,33 +73,54 @@ function parseSource(value, path) {
|
|
|
63
73
|
return value;
|
|
64
74
|
throw invalidReport(path);
|
|
65
75
|
}
|
|
66
|
-
function
|
|
67
|
-
if (value
|
|
68
|
-
return null;
|
|
69
|
-
if (!isRecord(value) ||
|
|
70
|
-
typeof value.installed !== "string" ||
|
|
71
|
-
typeof value.range !== "string" ||
|
|
72
|
-
typeof value.satisfied !== "boolean") {
|
|
76
|
+
function parseWorkspace(value, path) {
|
|
77
|
+
if (!isRecord(value))
|
|
73
78
|
throw invalidReport(path);
|
|
74
|
-
|
|
75
|
-
|
|
79
|
+
const location = parseLocation(value.location, path);
|
|
80
|
+
if (typeof value.registryDir !== "string" ||
|
|
81
|
+
!value.registryDir.startsWith("/") ||
|
|
82
|
+
typeof value.runtimeDir !== "string" ||
|
|
83
|
+
!value.runtimeDir.startsWith("/") ||
|
|
84
|
+
(value.schemaVersion !== null && value.schemaVersion !== 1) ||
|
|
85
|
+
(value.portRange !== null && !isPortRange(value.portRange)) ||
|
|
86
|
+
typeof value.hasDevServer !== "boolean")
|
|
87
|
+
throw invalidReport(path);
|
|
88
|
+
if (!location.exists &&
|
|
89
|
+
(value.schemaVersion !== null || value.portRange !== null || value.hasDevServer))
|
|
90
|
+
throw invalidReport(path);
|
|
91
|
+
if (location.exists && value.schemaVersion !== 1)
|
|
92
|
+
throw invalidReport(path);
|
|
93
|
+
if (!value.hasDevServer && value.portRange !== null)
|
|
94
|
+
throw invalidReport(path);
|
|
95
|
+
return {
|
|
96
|
+
location,
|
|
97
|
+
registryDir: value.registryDir,
|
|
98
|
+
runtimeDir: value.runtimeDir,
|
|
99
|
+
schemaVersion: value.schemaVersion,
|
|
100
|
+
portRange: value.portRange,
|
|
101
|
+
hasDevServer: value.hasDevServer,
|
|
102
|
+
};
|
|
76
103
|
}
|
|
77
104
|
function parseConfig(value, path) {
|
|
78
105
|
if (value === null)
|
|
79
106
|
return null;
|
|
80
|
-
if (!isRecord(value))
|
|
107
|
+
if (!isRecord(value) || Object.hasOwn(value, "cli") || Object.hasOwn(value, "portRange"))
|
|
108
|
+
throw invalidReport(path);
|
|
109
|
+
if (Object.hasOwn(value, "ticketIdPattern") || Object.hasOwn(value, "git"))
|
|
110
|
+
throw invalidReport(path);
|
|
111
|
+
if (value.conventions !== undefined && !isRecord(value.conventions))
|
|
112
|
+
throw invalidReport(path);
|
|
113
|
+
const ticketIdPattern = value.conventions?.ticketIdPattern;
|
|
114
|
+
const developerInstructions = value.developerInstructions;
|
|
115
|
+
if (developerInstructions !== undefined && typeof developerInstructions !== "string")
|
|
81
116
|
throw invalidReport(path);
|
|
82
|
-
const ticketIdPattern = value.ticketIdPattern;
|
|
83
117
|
const plans = parsePlans(value.plans, path);
|
|
84
|
-
const portRange = value.portRange;
|
|
85
118
|
if (ticketIdPattern !== undefined && typeof ticketIdPattern !== "string")
|
|
86
119
|
throw invalidReport(path);
|
|
87
|
-
if (portRange !== undefined && !isPortRange(portRange))
|
|
88
|
-
throw invalidReport(path);
|
|
89
120
|
return {
|
|
90
|
-
...(ticketIdPattern === undefined ? {} : { ticketIdPattern }),
|
|
121
|
+
...(ticketIdPattern === undefined ? {} : { conventions: { ticketIdPattern } }),
|
|
122
|
+
...(developerInstructions === undefined ? {} : { developerInstructions }),
|
|
91
123
|
...(plans === undefined ? {} : { plans }),
|
|
92
|
-
...(portRange === undefined ? {} : { portRange }),
|
|
93
124
|
};
|
|
94
125
|
}
|
|
95
126
|
function parsePlans(value, path) {
|
|
@@ -97,34 +128,69 @@ function parsePlans(value, path) {
|
|
|
97
128
|
return;
|
|
98
129
|
if (!isRecord(value))
|
|
99
130
|
throw invalidReport(path);
|
|
100
|
-
|
|
101
|
-
|
|
131
|
+
if (Object.hasOwn(value, "folder"))
|
|
132
|
+
throw invalidReport(path);
|
|
133
|
+
const repositoryFolder = value.repositoryFolder;
|
|
102
134
|
if (repositoryFolder !== undefined && typeof repositoryFolder !== "string")
|
|
103
135
|
throw invalidReport(path);
|
|
104
136
|
return repositoryFolder === undefined ? {} : { repositoryFolder };
|
|
105
137
|
}
|
|
106
|
-
//
|
|
138
|
+
// Registry keys remain AlignFirst's concern; carry effective placement and its origins.
|
|
107
139
|
function parseCompanion(value, path) {
|
|
108
140
|
if (value === null)
|
|
109
141
|
return null;
|
|
110
142
|
if (!isRecord(value) || typeof value.dir !== "string" || typeof value.exists !== "boolean") {
|
|
111
143
|
throw invalidReport(path);
|
|
112
144
|
}
|
|
113
|
-
|
|
145
|
+
if (value.defaultLocation !== "auto" &&
|
|
146
|
+
value.defaultLocation !== "project" &&
|
|
147
|
+
value.defaultLocation !== "companion")
|
|
148
|
+
throw invalidReport(path);
|
|
149
|
+
if (!isRecord(value.items))
|
|
150
|
+
throw invalidReport(path);
|
|
151
|
+
const items = parseItemRecord(value.items, path, (setting) => {
|
|
152
|
+
if (setting !== "auto" && setting !== "project" && setting !== "companion")
|
|
153
|
+
throw invalidReport(path);
|
|
154
|
+
return setting;
|
|
155
|
+
});
|
|
156
|
+
if (items._aligndev === "project")
|
|
157
|
+
throw invalidReport(path);
|
|
158
|
+
return { dir: value.dir, exists: value.exists, defaultLocation: value.defaultLocation, items };
|
|
114
159
|
}
|
|
115
160
|
function parseLocations(value, path) {
|
|
116
161
|
if (!isRecord(value))
|
|
117
162
|
throw invalidReport(path);
|
|
118
163
|
const location = (name) => parseLocation(value[name], path);
|
|
119
164
|
return {
|
|
120
|
-
|
|
165
|
+
alignfirst: location("alignfirst"),
|
|
121
166
|
".alignfirst-instructions": location(".alignfirst-instructions"),
|
|
122
|
-
|
|
167
|
+
developerInstructions: value.developerInstructions === null ? null : location("developerInstructions"),
|
|
168
|
+
workspaceRuntime: location("workspaceRuntime"),
|
|
123
169
|
docs: location("docs"),
|
|
124
170
|
".plans": location(".plans"),
|
|
125
171
|
_aligndev: location("_aligndev"),
|
|
126
172
|
};
|
|
127
173
|
}
|
|
174
|
+
function parseSelectionOrigins(value, path) {
|
|
175
|
+
return parseItemRecord(value, path, (origin) => {
|
|
176
|
+
if (origin !== "item" && origin !== "defaultLocation" && origin !== "builtin")
|
|
177
|
+
throw invalidReport(path);
|
|
178
|
+
return origin;
|
|
179
|
+
});
|
|
180
|
+
}
|
|
181
|
+
function parseItemRecord(value, path, parse) {
|
|
182
|
+
if (!isRecord(value))
|
|
183
|
+
throw invalidReport(path);
|
|
184
|
+
return {
|
|
185
|
+
alignfirst: parse(value.alignfirst),
|
|
186
|
+
".alignfirst-instructions": parse(value[".alignfirst-instructions"]),
|
|
187
|
+
developerInstructions: parse(value.developerInstructions),
|
|
188
|
+
workspaceRuntime: parse(value.workspaceRuntime),
|
|
189
|
+
docs: parse(value.docs),
|
|
190
|
+
".plans": parse(value[".plans"]),
|
|
191
|
+
_aligndev: parse(value._aligndev),
|
|
192
|
+
};
|
|
193
|
+
}
|
|
128
194
|
function parseLocation(value, path) {
|
|
129
195
|
if (!isRecord(value) ||
|
|
130
196
|
typeof value.path !== "string" ||
|
|
@@ -138,7 +204,14 @@ function invalidReport(path) {
|
|
|
138
204
|
return new Error(`Invalid alignfirst config report for ${path}`);
|
|
139
205
|
}
|
|
140
206
|
function isPortRange(value) {
|
|
141
|
-
return isRecord(value) &&
|
|
207
|
+
return (isRecord(value) &&
|
|
208
|
+
typeof value.first === "number" &&
|
|
209
|
+
typeof value.last === "number" &&
|
|
210
|
+
Number.isInteger(value.first) &&
|
|
211
|
+
Number.isInteger(value.last) &&
|
|
212
|
+
value.first >= 1 &&
|
|
213
|
+
value.last <= 65535 &&
|
|
214
|
+
value.first <= value.last);
|
|
142
215
|
}
|
|
143
216
|
function isRecord(value) {
|
|
144
217
|
return typeof value === "object" && value !== null;
|
|
@@ -147,6 +220,6 @@ function isRecord(value) {
|
|
|
147
220
|
export function companionInUse(report, items) {
|
|
148
221
|
return items.some((item) => {
|
|
149
222
|
const location = report.locations[item];
|
|
150
|
-
return location
|
|
223
|
+
return location?.in === "companion" && location.exists;
|
|
151
224
|
});
|
|
152
225
|
}
|
package/dist/project/plans.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { CommandForms } from "../command-form.js";
|
|
2
|
-
import type { GitContext } from "
|
|
2
|
+
import type { GitContext } from "@alignfirst/workspace/git";
|
|
3
3
|
import { type ProjectReport } from "./layout.js";
|
|
4
4
|
export interface PlansContext extends GitContext {
|
|
5
5
|
alignfirstCommand: string[];
|
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/project/render.js
CHANGED
|
@@ -88,7 +88,7 @@ export function renderProjectStatus(details) {
|
|
|
88
88
|
` Config source: ${details.configSource ?? "(none)"}`,
|
|
89
89
|
` Companion: ${renderCompanion(details.companion)}`,
|
|
90
90
|
` AlignDev profile: ${renderNullableValue(details.aligndev?.profile ?? null)}`,
|
|
91
|
-
`
|
|
91
|
+
` Developer instructions: ${renderLocation(details.locations.developerInstructions)}`,
|
|
92
92
|
` Work files: ${renderLocation(details.locations[".plans"])}`,
|
|
93
93
|
` Work-files folder: ${renderNullableValue(details.plansFolder)}`,
|
|
94
94
|
` Ticket id pattern: ${renderNullableValue(details.ticketIdPattern)}`,
|
|
@@ -108,6 +108,8 @@ function renderCompanion(companion) {
|
|
|
108
108
|
return renderPath(companion.dir, companion.exists);
|
|
109
109
|
}
|
|
110
110
|
function renderLocation(location) {
|
|
111
|
+
if (location === null)
|
|
112
|
+
return "(not configured)";
|
|
111
113
|
return renderPath(location.path, location.exists);
|
|
112
114
|
}
|
|
113
115
|
function renderPath(path, exists) {
|
package/dist/project/status.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { ProjectInventory } from "./discovery.js";
|
|
2
|
-
import type { AligndevProjectSettings, CompanionReport, ConfigSource,
|
|
2
|
+
import type { AligndevProjectSettings, CompanionReport, ConfigSource, ProjectLocations } from "./layout.js";
|
|
3
3
|
import type { PortRange } from "./markers.js";
|
|
4
4
|
export interface ProjectDetails {
|
|
5
5
|
name: string;
|
|
@@ -13,7 +13,7 @@ export interface ProjectDetails {
|
|
|
13
13
|
configSource: ConfigSource | null;
|
|
14
14
|
companion: CompanionReport | null;
|
|
15
15
|
aligndev: AligndevProjectSettings | null;
|
|
16
|
-
locations:
|
|
16
|
+
locations: ProjectLocations;
|
|
17
17
|
workspaces: string[];
|
|
18
18
|
worktrees: ProjectWorktree[];
|
|
19
19
|
}
|
package/dist/project/status.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { execFileSync } from "node:child_process";
|
|
2
2
|
import { realpathSync } from "node:fs";
|
|
3
3
|
import { basename } from "node:path";
|
|
4
|
-
import { readWorktrees } from "
|
|
4
|
+
import { readWorktrees } from "@alignfirst/workspace/git";
|
|
5
5
|
import { errorMessage, isNodeError } from "../errors.js";
|
|
6
6
|
const URL_WITH_AUTHORITY = /^[A-Za-z][A-Za-z\d+.-]*:\/\//u;
|
|
7
7
|
export function getProjectStatus(inventory, projectPath) {
|
|
@@ -32,7 +32,7 @@ function buildProjectDetails(project) {
|
|
|
32
32
|
portRange: project.portRange ?? null,
|
|
33
33
|
portRangeCode: project.portRangeCode ?? null,
|
|
34
34
|
plansFolder: project.description.config?.plans?.repositoryFolder ?? null,
|
|
35
|
-
ticketIdPattern: project.description.config?.ticketIdPattern ?? null,
|
|
35
|
+
ticketIdPattern: project.description.config?.conventions?.ticketIdPattern ?? null,
|
|
36
36
|
configSource: project.description.source,
|
|
37
37
|
companion: project.description.companion,
|
|
38
38
|
aligndev: project.description.aligndev,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "aligndev",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.30.0",
|
|
4
4
|
"license": "CC0-1.0",
|
|
5
5
|
"author": "Thomas MUR",
|
|
6
6
|
"description": "The AlignDev CLI: the assistant's playbook, coding-agent delegation, and project inventory.",
|
|
@@ -37,6 +37,10 @@
|
|
|
37
37
|
"publishConfig": {
|
|
38
38
|
"access": "public"
|
|
39
39
|
},
|
|
40
|
+
"dependencies": {
|
|
41
|
+
"@alignfirst/docmap": "~0.12.0",
|
|
42
|
+
"@alignfirst/workspace": "~0.42.0"
|
|
43
|
+
},
|
|
40
44
|
"devDependencies": {
|
|
41
45
|
"@types/node": "~26.6.5",
|
|
42
46
|
"rimraf": "~6.1.3",
|
package/templates/guide/code.md
CHANGED
|
@@ -9,7 +9,7 @@ Run a coding agent through AlignFirst protocols with `{{ALIGNDEV}} code`. It wra
|
|
|
9
9
|
|
|
10
10
|
**Never implement, investigate, or modify the codebase yourself. Your role is to delegate and guide the agent.**
|
|
11
11
|
|
|
12
|
-
Run `{{ALIGNDEV}} code` from the root of the selected worktree, so the agent works in the right repository. The project must have usable `.plans/`, in the repository or in its companion directory: `{{ALIGNFIRST}} plans check` verifies it, and `{{
|
|
12
|
+
Run `{{ALIGNDEV}} code` from the root of the selected worktree, so the agent works in the right repository. The project must have usable `.plans/`, in the repository or in its companion directory: `{{ALIGNFIRST}} plans check` verifies it, and `{{GUIDE}} work-files-setup` prepares it.
|
|
13
13
|
|
|
14
14
|
{{ALIGNFIRST_SETUP}}
|
|
15
15
|
|
|
@@ -29,7 +29,12 @@ Under OpenClaw, background it through the `exec` tool:
|
|
|
29
29
|
|
|
30
30
|
`{{ALIGNDEV}} code <command> <options> ; openclaw system event --text "aligndev code run finished — read its session file and report to the user" --mode now --session-key <KEY>`
|
|
31
31
|
|
|
32
|
+
{{#thread}}
|
|
32
33
|
Chain with `;` (never `&&`) so a failed run wakes you too, and keep the `;` on the same line as the `{{ALIGNDEV}} code` command: a line that starts with `;` is a shell syntax error, the wake command never runs, and the run's completion is lost. The wake may reach you as a bare heartbeat with the text dropped, and OpenClaw's own `Exec completed` notice may lag behind it. Never wait for either text.
|
|
34
|
+
{{/thread}}
|
|
35
|
+
{{#app}}
|
|
36
|
+
Chain with `;` (never `&&`) so a failed run wakes you too, and keep the `;` on the same line as the `{{ALIGNDEV}} code` command: a line that starts with `;` is a shell syntax error, the wake command never runs, and the run's completion is lost. The wake may reach you as a bare heartbeat with the text dropped. Never wait for its text.
|
|
37
|
+
{{/app}}
|
|
33
38
|
- Pass `background: true` and `timeoutSeconds: 0` (no kill timer). Never rely on the auto-yield or a finite timeout.
|
|
34
39
|
- For a run launched without `--ticket` or `--no-ticket`, pass `--meta <KEY>` with this session's key. `{{ALIGNDEV}} code status --meta <KEY>` then finds its result among concurrent runs in the shared main worktree.
|
|
35
40
|
- Set the exec `workdir` to the project root as an **absolute** path (`~` is not expanded there), or `cd` into the project inside the command itself.
|
|
@@ -42,6 +47,10 @@ As soon as the run is backgrounded, tell the user — in the user's language —
|
|
|
42
47
|
## After a background run completes
|
|
43
48
|
|
|
44
49
|
The chained wake fires when the backgrounded `{{ALIGNDEV}} code` exits. This session receives a heartbeat, often as a plain heartbeat poll with no message text. A run counts as pending while it is running **and until its outcome is reported**.
|
|
50
|
+
{{#app}}
|
|
51
|
+
|
|
52
|
+
In this conversation, the run's exit brings two turns, about ten seconds apart: OpenClaw's `Exec completed` notice, then the chained wake as a heartbeat. Both are completion wakes. The first finds the run pending and reports it; the second finds it reported.
|
|
53
|
+
{{/app}}
|
|
45
54
|
|
|
46
55
|
**First, decide whether this heartbeat needs a report.** A heartbeat is a completion wake only while a run is pending. Once you have reported the outcome, later heartbeats for that run need nothing. End them with exactly `HEARTBEAT_OK`, alone.
|
|
47
56
|
|
|
@@ -54,7 +63,7 @@ Any heartbeat received while an `{{ALIGNDEV}} code` run is **still pending** ent
|
|
|
54
63
|
|
|
55
64
|
For a consultation, answer it directly from the findings; include a failure or uncertainty when relevant. The coding-run template above is for change reports.
|
|
56
65
|
|
|
57
|
-
The report is the plain text that ends the turn
|
|
66
|
+
The report is the plain text that ends the turn. It must be the turn's **final message**: text written between tool calls may never post. Never follow it with `NO_REPLY`, `HEARTBEAT_OK`, a duplicate message-tool post, or another tool call.
|
|
58
67
|
3. **Don't reconstruct what happened.** Verifying the result is what your operating instructions prescribe; re-deriving the run's story is not: no re-running the agent, no fetch/merge, no `git` archaeology to double-check its account — the session file is authoritative for that.
|
|
59
68
|
|
|
60
69
|
Reporting the run is not calling the work done: the report relays the agent's claim plus what you verified. When your verification finds a failing check, the report says so, and the fix is new work — a fresh run with its own completion wake; the wake you were answering is discharged by your report.
|
|
@@ -89,7 +98,7 @@ Retain these distinct values for each run:
|
|
|
89
98
|
Prepare the literal delegated prompt in a UTF-8 file, then launch the ordinary quoted shell command through `background` with `action: "start"` and `cwd`. Supply `--quiet --meta <unique-run-key>` yourself; the extension never parses or appends CLI options. This example assumes `/tmp/aligndev-request.txt` already contains the request. Generate a fresh key for every actual launch; the UUID below illustrates one run:
|
|
90
99
|
|
|
91
100
|
```json
|
|
92
|
-
{"action":"start","command":
|
|
101
|
+
{"action":"start","command":{{BACKGROUND_COMMAND_JSON}},"cwd":"/srv/projects/example","label":"coding run"}
|
|
93
102
|
```
|
|
94
103
|
|
|
95
104
|
For resume, use `{{ALIGNDEV}} code resume <sessionId> --message-file <path> --quiet --meta <fresh-run-key>` from the original worktree. A Pi child must resume from its recorded directory. Use safe shell quoting for paths and options; never interpolate raw user text into a command. A quoted heredoc with `--message-file -` is another literal-input route.
|