aligndev 0.29.0 → 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 CHANGED
@@ -33,15 +33,17 @@ A task can also start at any intermediate step.
33
33
 
34
34
  For a coding-agent assistant, parent host and delegated child are independent: a coding profile selects Claude Code, Codex or Pi. Without a named selection, the detected parent kind selects a matching profile or built-in child defaults. OpenClaw deployment templates offer all three agents on Slack or Discord, with explicit profiles and inventoried default/custom native stores. The Pi overlay uses a protected absolute-Node launcher while retaining project PATH. Its [deployment boundary](https://github.com/paleo/alignfirst/blob/main/skills/alignfirst-setup-guide/references/aligndev-openclaw.md#deployment-gate) explicitly permits writable native `auth.json` and adjacent locks for OAuth renewal. That file can persist same-account executable API-key commands; this is account-level persistence, not administrator privilege escalation. Other managed resources and trust retain controlled-maintenance protection. Project trust is not a sandbox, and offline checks do not certify live deployment.
35
35
 
36
+ ## Configuration boundary
37
+
38
+ AlignDev requires the workspace-aware `alignfirst config --json` report: top-level `workspace` metadata with absolute registry/runtime paths, `selectionOrigins`, logical locations and independent `aligndev` selection. One selected `alignfirst.json`/`.jsonc` with `schemaVersion: 1` holds nested conventions, plans, explicit developer instructions and optional recipes. Project configuration rejects unknown properties. Companion/global settings retain tolerant warnings. Inventory ranges come only from workspace `devServer.ports`; `project free-ports` looks up a free block without reserving it.
39
+
36
40
  ## Start in Claude Code, Codex or Pi
37
41
 
38
42
  The project needs usable AlignFirst work files, untracked by the project's own repository or in a [companion directory](https://github.com/paleo/alignfirst/tree/main/packages/alignfirst#companion-directories). A separate work-files repository may track them. The [setup guide](https://github.com/paleo/alignfirst/blob/main/skills/alignfirst-setup-guide/references/coding-agent-assistant.md) prepares it. `alignfirst plans check --json` verifies them, from the main worktree or a linked one. AlignFirst refuses effective plans tracked by the project's own repository. Missing or project-tracked effective plans require authorized companion preparation through the `work-files-setup` topic of `aligndev guide`; existing project content stays untouched and is not copied.
39
43
 
40
- Full workspace tooling is optional. The assistant follows the project's documented tooling when present, including non-Node implementations; otherwise `aligndev worktree` creates or prepares an isolated Git worktree without installation or tracked configuration changes. It shares usable untracked project plans and optional `.local` through locally excluded symlinks, or uses companion plans directly. Readiness covers Git and work files only; dependency installation, builds, tests and application lifecycle follow the repository's commands separately.
41
-
42
- For externally created worktrees, tools such as Paseo can run `npx -y aligndev worktree setup` as a post-creation hook inside the target. With no path, setup discovers the current worktree root even from a subdirectory; an explicit path must name an exact registered root of the same repository. Setup preserves the branch, index and unrelated files. Conflicts remain untouched; repair the reported problem and retry the idempotent setup to complete partial preparation. Setup validates existing plans without provisioning or migrating them.
44
+ The assistant directly runs `alignfirst workspace` for configured and manifest-free projects on every stack. Project recipes live in the selected merged `alignfirst.json`/`.jsonc`, from project or companion; no wrapper or local kernel dependency is required. Prepare usable effective plans and selected runtime storage first. Local storage requires ignored, untracked `.local-wt/`; companion storage needs no checkout runtime directory. Without a manifest, readiness is protocol-ready: no installation, build, ports or services are implied. Coding delegation and project-specific commands remain separate.
43
45
 
44
- The external tool owns Git creation and deletion, with project-specific preparation and shutdown handled separately. There is no `aligndev worktree teardown` command or lightweight pre-deletion hook. AlignDev's own removal refuses dirty worktrees, preserves branches and shared targets, and does not stop processes or tear down infrastructure. See `aligndev worktree --help` for the command reference.
46
+ External tools such as Paseo run `npx -y alignfirst workspace setup` inside their selected checkout, then `workspace teardown` before their own deletion. Setup preserves the path/branch and retains partial preparation on failure for retry. Teardown stops/purges and releases state while preserving files and Git; remove additionally performs protected Git deletion and preserves branches. Failed cleanup retains identity even after PIDs exit. Adoption does not transfer external deletion ownership. See `alignfirst workspace --guide` and [the upgrade runbook](https://github.com/paleo/alignfirst/blob/main/docs/upgrading-multi-stack-workspaces.md).
45
47
 
46
48
  The child needs network access and access to its selected work files. Parent-host elevation and the child's permission policy are separate. A shared symlink grants no sandbox permission. In native Codex 0.162.1 host probes, normal `workspace-write` denied writes through shared project `.plans` and `.local` links (`Errno 30`). Prepared companion plans passed through the existing `--add-dir <companion>` route; shared `.local` and outside-root writes remained denied. Report denied real paths. For companion plans, obtain approval through the `work-files-setup` topic of `aligndev guide`, preserving existing project files. Do not silently bypass the sandbox or grant the whole main repository write access.
47
49
 
@@ -190,7 +192,7 @@ npx -y skills add https://github.com/paleo/alignfirst --global --skill alignfirs
190
192
 
191
193
  Deployments require null or a string for every coding profile and enabled explicit quota source; omission is invalid there. Generated service defaults use null. Inventory still records absolute filesystem paths, while native commands unset the directory variable for null or set its resolved value for a string.
192
194
 
193
- Then ask the agent to create an assistant. The skill collects the deployment values, renders one Slack or Discord variant and one Claude Code, Codex or Pi variant, and writes the installation, security, operation and recovery runbooks. Each managed project receives the preparation contract: project context, usable work files, docmap, runtime procedures and a project-specific `DEVELOPERS.md`, in the repository or its companion. Full workspace tooling is optional; lightweight worktrees provide isolation when it is absent.
195
+ Then ask the agent to create an assistant. The skill collects the deployment values, renders one Slack or Discord variant and one Claude Code, Codex or Pi variant, and writes the installation, security, operation and recovery runbooks. Each managed project receives the preparation contract: project context, usable work files, docmap, runtime procedures and an explicitly referenced developer guide, in the repository or its companion. `alignfirst developer-instructions` prints conventions and that content without filename discovery. The workspace recipe is optional; default preparation is protocol-ready.
194
196
 
195
197
  ## Under the Hood
196
198
 
@@ -36,8 +36,7 @@ export function forwardSettingsWarnings(stderr) {
36
36
  function isSettingsWarning(line) {
37
37
  if (/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(line))
38
38
  return false;
39
- return (/^Warning: ignoring unknown (?:\.alignfirst\.json|companion registry) setting /u.test(line) ||
40
- /^Warning: .+: plans\.folder is deprecated; rename it to plans\.repositoryFolder\. See "Rename the Work-Files Folder Setting" in the setup guide's alignfirst-upgrade reference\.$/u.test(line));
39
+ return /^Warning: ignoring unknown companion registry setting /u.test(line);
41
40
  }
42
41
  export function describeAlignfirst(command, cwd, env) {
43
42
  const runner = ["npx", "bunx", "pnpm", "yarn"].includes(command[0]);
package/dist/cli.js CHANGED
@@ -9,7 +9,6 @@ import { errorMessage } from "./errors.js";
9
9
  import { runGuide } from "./guide/guide-cli.js";
10
10
  import { readPackageVersion } from "./package-version.js";
11
11
  import { runProject } from "./project/project-cli.js";
12
- import { runWorktree } from "./worktree/worktree-cli.js";
13
12
  export async function main(options) {
14
13
  const ctx = resolveContext(options);
15
14
  const [command, ...tokens] = (options?.argv ?? process.argv).slice(2);
@@ -21,17 +20,12 @@ export async function main(options) {
21
20
  ctx.stdout.write(`${readPackageVersion()}\n`);
22
21
  return 0;
23
22
  }
24
- if (command !== "code" &&
25
- command !== "project" &&
26
- command !== "guide" &&
27
- command !== "worktree") {
23
+ if (command !== "code" && command !== "project" && command !== "guide") {
28
24
  const error = command === undefined ? "Error: no command given." : `Error: unknown command "${command}".`;
29
25
  ctx.stderr.write(`${error}\n\n${renderHelp(ctx.forms.aligndev)}`);
30
26
  return 1;
31
27
  }
32
28
  try {
33
- if (command === "worktree")
34
- return runWorktree(tokens, ctx);
35
29
  if (command === "code")
36
30
  return await runCode(tokens, () => loadConfig(ctx.home), ctx);
37
31
  const config = loadConfig(ctx.home);
@@ -51,10 +45,6 @@ function renderHelp(aligndev) {
51
45
  `${aligndev} project <command> [<options>]`,
52
46
  "List projects, check their inventory, claim port ranges.",
53
47
  ],
54
- [
55
- `${aligndev} worktree <command> [<options>]`,
56
- "Create or prepare lightweight Git worktrees; list and safely remove them.",
57
- ],
58
48
  [
59
49
  `${aligndev} guide [--channel <surface>] [<topic>]`,
60
50
  "Print the assistant's playbook and guides.",
@@ -30,7 +30,7 @@ const SESSION_OPTIONS = {
30
30
  };
31
31
  // Items the agent would not find in the repository: a new session gets `alignfirst context`.
32
32
  const CONTEXT_COMPANION_ITEMS = [
33
- ".alignfirst.json",
33
+ "alignfirst",
34
34
  ".alignfirst-instructions",
35
35
  "docs",
36
36
  ".plans",
@@ -6,7 +6,6 @@ import { errorMessage } from "../errors.js";
6
6
  import { readProjectReport } from "../project/layout.js";
7
7
  import { renderProjectsGuideForRoot } from "../project/project-cli.js";
8
8
  import { renderCodeGuide } from "./code-guide.js";
9
- import { resolveGuideFile } from "./guide-file.js";
10
9
  import { isSurface, renderGuideTemplate, SURFACES, } from "./render-template.js";
11
10
  import { ENTRY_TOPICS, guideContextOf, PLAYBOOK, PLAYBOOK_DISPATCHER, PLAYBOOK_TOPICS, surfacesServing, } from "./topics.js";
12
11
  export function runGuide(tokens, config, ctx) {
@@ -119,15 +118,13 @@ function renderCodeTopic(active, config, ctx, profile) {
119
118
  const models = resolveModels(code.agent, code.models, code.modelAliases);
120
119
  return renderCodeGuide(active, code.agent, models, code.defaultModel, ctx.forms, code.profile, describeNativeStorage(code));
121
120
  }
122
- // An entry topic prints after the playbook. Under codingAgent, the playbook topics read the
123
- // project's guide file; no other guide has a condition block.
121
+ // An entry topic prints after the playbook.
124
122
  function renderPlaybookTopic(topic, active, config, ctx) {
125
123
  assertPlaybookTopic(topic, active);
126
- const topicActive = active.platform === "codingAgent" ? { ...active, guideFile: resolveGuideFile(ctx) } : active;
127
- const text = renderPlaybookTemplate(topic, topicActive, config, ctx.forms);
124
+ const text = renderPlaybookTemplate(topic, active, config, ctx.forms);
128
125
  if (!ENTRY_TOPICS.includes(topic))
129
126
  return text;
130
- return `${renderPlaybookTemplate(PLAYBOOK, topicActive, config, ctx.forms)}\n\n${text}`;
127
+ return `${renderPlaybookTemplate(PLAYBOOK, active, config, ctx.forms)}\n\n${text}`;
131
128
  }
132
129
  function assertPlaybookTopic(topic, active) {
133
130
  const topics = PLAYBOOK_TOPICS[guideContextOf(active)];
@@ -1,15 +1,11 @@
1
1
  import type { CommandForms } from "../command-form.js";
2
2
  import { type Platform } from "../config.js";
3
3
  export declare const SURFACES: readonly ["slack", "discord", "app"];
4
- declare const GUIDE_FILE_CONDITIONS: readonly ["developers", "readme", "noGuide"];
5
4
  export type Surface = (typeof SURFACES)[number];
6
- export type GuideFileCondition = (typeof GUIDE_FILE_CONDITIONS)[number];
7
5
  export interface ActiveBlocks {
8
6
  platform: Platform;
9
7
  surface?: Surface;
10
- guideFile?: GuideFileCondition;
11
8
  }
12
9
  export declare function renderGuideTemplate(name: string, active: ActiveBlocks, forms: CommandForms, values?: Readonly<Record<string, string>>): string;
13
10
  export declare function renderBlocks(text: string, active: ActiveBlocks, templateName: string): string;
14
11
  export declare function isSurface(name: string): name is Surface;
15
- export {};
@@ -1,9 +1,6 @@
1
1
  import { PLATFORMS } from "../config.js";
2
2
  import { readTemplate } from "../templates.js";
3
3
  export const SURFACES = ["slack", "discord", "app"];
4
- const GUIDE_FILE_CONDITIONS = ["developers", "readme", "noGuide"];
5
- // Active for both guide files: `developers` and `readme`.
6
- const HAS_GUIDE = "hasGuide";
7
4
  // Derived facts: `thread` holds on Slack and Discord; `conversation` in an app conversation and
8
5
  // under codingAgent.
9
6
  const THREAD = "thread";
@@ -35,7 +32,7 @@ function guidePlaceholder(active, forms) {
35
32
  }
36
33
  // A block is `{{#<name>}}` … `{{/<name>}}`, each marker alone on its line, and names a fact. A
37
34
  // 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.
35
+ // `codingAgent` block; `conversation` sits anywhere.
39
36
  // A line is kept when every block around it holds. The runs of empty lines that removed blocks
40
37
  // leave collapse to one.
41
38
  export function renderBlocks(text, active, templateName) {
@@ -66,9 +63,7 @@ function isActive(name, active) {
66
63
  return active.surface === "slack" || active.surface === "discord";
67
64
  if (name === CONVERSATION)
68
65
  return active.surface === "app" || active.platform === "codingAgent";
69
- if (name === HAS_GUIDE)
70
- return active.guideFile === "developers" || active.guideFile === "readme";
71
- return name === active.platform || name === active.surface || name === active.guideFile;
66
+ return name === active.platform || name === active.surface;
72
67
  }
73
68
  function openBlock(name, line, open, templateName) {
74
69
  const insideCodingAgent = open.some((block) => block.name === "codingAgent");
@@ -88,12 +83,6 @@ function openBlock(name, line, open, templateName) {
88
83
  }
89
84
  if (name === CONVERSATION)
90
85
  return { name, line };
91
- if (isCondition(name)) {
92
- if (!insideCodingAgent) {
93
- throw blockError(templateName, line, `condition block "${name}" outside a codingAgent block`);
94
- }
95
- return { name, line };
96
- }
97
86
  throw blockError(templateName, line, `unknown block "${name}"`);
98
87
  }
99
88
  function closeBlock(name, line, open, templateName) {
@@ -105,11 +94,7 @@ function closeBlock(name, line, open, templateName) {
105
94
  open.pop();
106
95
  }
107
96
  function isBlockName(name) {
108
- return (isPlatform(name) ||
109
- isSurface(name) ||
110
- name === THREAD ||
111
- name === CONVERSATION ||
112
- isCondition(name));
97
+ return isPlatform(name) || isSurface(name) || name === THREAD || name === CONVERSATION;
113
98
  }
114
99
  function isPlatform(name) {
115
100
  return PLATFORMS.includes(name);
@@ -117,9 +102,6 @@ function isPlatform(name) {
117
102
  export function isSurface(name) {
118
103
  return SURFACES.includes(name);
119
104
  }
120
- function isCondition(name) {
121
- return name === HAS_GUIDE || GUIDE_FILE_CONDITIONS.includes(name);
122
- }
123
105
  function blockError(templateName, line, detail) {
124
106
  return new Error(`Error: template ${templateName}, line ${line}: ${detail}.`);
125
107
  }
@@ -1,10 +1,10 @@
1
- import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
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 PROJECT_CONFIG_FILENAME = ".alignfirst.json";
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 (existsSync(join(candidate.path, PROJECT_CONFIG_FILENAME))) {
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.config?.portRange === undefined
89
+ ...(description.workspace.portRange === null
90
90
  ? {}
91
- : { portRange: description.config.portRange }),
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
  }
@@ -1,33 +1,46 @@
1
1
  import type { PortRange } from "./markers.js";
2
- export type ItemName = ".alignfirst.json" | ".alignfirst-instructions" | "DEVELOPERS.md" | "docs" | ".plans" | "_aligndev";
2
+ export type ItemName = "alignfirst" | ".alignfirst-instructions" | "developerInstructions" | "workspaceRuntime" | "docs" | ".plans" | "_aligndev";
3
3
  export interface ProjectReport {
4
4
  source: ConfigSource | null;
5
- cli: ProjectCliReport | null;
5
+ workspace: WorkspaceConfigReport;
6
6
  config: ProjectConfigView | null;
7
7
  companion: CompanionReport | null;
8
8
  aligndev: AligndevProjectSettings | null;
9
- locations: Record<ItemName, ItemLocation>;
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 ProjectCliReport {
16
- installed: string;
17
- range: string;
18
- satisfied: boolean;
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
- ticketIdPattern?: string;
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";
@@ -30,22 +30,32 @@ function firstLine(value) {
30
30
  function isOutdatedReport(value) {
31
31
  return (isRecord(value) &&
32
32
  (!Object.hasOwn(value, "aligndev") ||
33
- !(isRecord(value.locations) && ".alignfirst-instructions" in value.locations)));
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 profile-aware ` +
37
- 'alignfirst config --json contract (top-level "aligndev"). Upgrade alignfirst.');
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
- cli: parseCli(value.cli, path),
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 parseCli(value, path) {
67
- if (value === null)
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
- return { installed: value.installed, range: value.range, satisfied: value.satisfied };
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
- // Before alignfirst 0.12.0, the report named this key `folder`.
101
- const repositoryFolder = value.repositoryFolder ?? value.folder;
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
- // The report's other companion fields (`key`, `items`) are alignfirst's concern.
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
- return { dir: value.dir, exists: value.exists };
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
- ".alignfirst.json": location(".alignfirst.json"),
165
+ alignfirst: location("alignfirst"),
121
166
  ".alignfirst-instructions": location(".alignfirst-instructions"),
122
- "DEVELOPERS.md": location("DEVELOPERS.md"),
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) && typeof value.first === "number" && typeof value.last === "number";
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.in === "companion" && location.exists;
223
+ return location?.in === "companion" && location.exists;
151
224
  });
152
225
  }
@@ -1,5 +1,5 @@
1
1
  import type { CommandForms } from "../command-form.js";
2
- import type { GitContext } from "../worktree/git.js";
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[];
@@ -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
- ` DEVELOPERS.md: ${renderLocation(details.locations["DEVELOPERS.md"])}`,
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) {
@@ -1,5 +1,5 @@
1
1
  import type { ProjectInventory } from "./discovery.js";
2
- import type { AligndevProjectSettings, CompanionReport, ConfigSource, ItemLocation, ItemName } from "./layout.js";
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: Record<ItemName, ItemLocation>;
16
+ locations: ProjectLocations;
17
17
  workspaces: string[];
18
18
  worktrees: ProjectWorktree[];
19
19
  }
@@ -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 "../worktree/git.js";
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.29.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.",
@@ -38,7 +38,8 @@
38
38
  "access": "public"
39
39
  },
40
40
  "dependencies": {
41
- "@alignfirst/docmap": "~0.12.0"
41
+ "@alignfirst/docmap": "~0.12.0",
42
+ "@alignfirst/workspace": "~0.42.0"
42
43
  },
43
44
  "devDependencies": {
44
45
  "@types/node": "~26.6.5",