aligndev 0.0.0 → 0.19.0

package/dist/code/session-file.js

@@ -0,0 +1,263 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+export const RESULT_MARKER = "\n---- Result ----\n";
+// `sessionsDir` is the `.plans`-shaped directory holding the session directories: the resolved
+// `_aligndev` location, which is the resolved `.plans` unless the companion holds a separate tree.
+export function resolveSessionFilePath(sessionsDir, ticket, now, fileExists = existsSync) {
+    const dir = join(sessionsDir, ...(ticket === undefined ? [] : [ticket]), "_aligndev");
+    const stamp = formatStamp(now);
+    let candidate = join(dir, `${stamp}.md`);
+    let suffix = 2;
+    while (fileExists(candidate)) {
+        candidate = join(dir, `${stamp}-${suffix}.md`);
+        ++suffix;
+    }
+    return candidate;
+}
+// Writes the initial `running` header. Present before the run starts so an interrupted run still
+// leaves an auditable record; the terminal frontmatter rewrite happens on completion.
+export function writeInitialSessionFile(sessionFilePath, frontmatter) {
+    const header = `${serializeFrontmatter(frontmatter)}\n`;
+    mkdirSync(dirname(sessionFilePath), { recursive: true });
+    writeFileSync(sessionFilePath, header);
+}
+// Appends the result block, then rewrites the frontmatter in place. Append-first keeps the tailed
+// transcript intact until the single terminal rewrite.
+export function applyCompletion(sessionFilePath, update) {
+    const content = readFileSync(sessionFilePath, "utf-8");
+    const { frontmatter, body } = splitSessionFile(content);
+    const updated = {
+        ...frontmatter,
+        status: update.status,
+        endedAt: update.endedAt,
+        exitReason: update.exitReason,
+        sessionId: update.sessionId ?? frontmatter.sessionId,
+        contextTokens: update.contextTokens ?? frontmatter.contextTokens,
+        contextCompacted: update.contextCompacted ?? frontmatter.contextCompacted,
+        contextTokensError: update.contextTokensError ?? frontmatter.contextTokensError,
+    };
+    const resultBlock = `${RESULT_MARKER}\n${update.result}\n`;
+    writeFileSync(sessionFilePath, `${serializeFrontmatter(updated)}\n${body}${resultBlock}`);
+}
+export function appendTranscript(sessionFilePath, text) {
+    writeFileSync(sessionFilePath, text, { flag: "a" });
+}
+// Reads back a completed (or in-progress) session file — the durable result handoff a waking
+// OpenClaw agent or a human reads: frontmatter status/sessionId plus the `---- Result ----` block.
+export function readCompletion(sessionFilePath) {
+    const content = readFileSync(sessionFilePath, "utf-8");
+    const { frontmatter } = splitSessionFile(content);
+    // `lastIndexOf`, not `indexOf`: `applyCompletion` always appends the real result block last, so a
+    // `---- Result ----` echoed earlier in the transcript body (e.g. the agent printing a session
+    // file) must not truncate the actual result.
+    const markerIndex = content.lastIndexOf(RESULT_MARKER);
+    const result = markerIndex === -1 ? undefined : content.slice(markerIndex + RESULT_MARKER.length).trim();
+    return { frontmatter, result };
+}
+export function reconcileSessionFile(sessionFilePath, now = new Date()) {
+    const completion = readCompletion(sessionFilePath);
+    const update = interruptedCompletion(completion.frontmatter, now);
+    if (!update)
+        return completion;
+    applyCompletion(sessionFilePath, update);
+    return {
+        frontmatter: {
+            ...completion.frontmatter,
+            status: update.status,
+            endedAt: update.endedAt,
+            exitReason: update.exitReason,
+        },
+        result: update.result,
+    };
+}
+function interruptedCompletion(frontmatter, now) {
+    if (frontmatter.status !== "running" || isRecordedProcessAlive(frontmatter))
+        return;
+    return {
+        status: "failed",
+        endedAt: now.toISOString(),
+        exitReason: "terminated",
+        sessionId: frontmatter.sessionId,
+        result: `Sealed as interrupted: process ${frontmatter.pid ?? "(unknown)"} is gone.`,
+    };
+}
+function isRecordedProcessAlive(frontmatter) {
+    if (frontmatter.pid === null || !isPidAlive(frontmatter.pid))
+        return false;
+    if (frontmatter.pidStartTime === null)
+        return true;
+    const currentStartTime = readPidStartTime(frontmatter.pid);
+    return currentStartTime === null || currentStartTime === frontmatter.pidStartTime;
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code !== "ESRCH";
+    }
+}
+export function readPidStartTime(pid) {
+    if (process.platform !== "linux")
+        return null;
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, "utf-8");
+        const fieldsAfterCommand = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+        return fieldsAfterCommand[19] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// Lists every active session record: `<sessionsDir>/_aligndev/*.md` plus
+// `<sessionsDir>/<ticket>/_aligndev/*.md`. Archived tickets move under `_archives/` and leave the
+// registry. The session files are the registry — no separate registry file.
+// Self-healing: a `running` record whose pid is gone is a stale leftover from an interrupted run;
+// it gets sealed in passing so the launch guards never block on dead state. The returned records
+// reflect the post-healing state.
+export function listSessionRecords(sessionsDir) {
+    const sessionDirs = [join(sessionsDir, "_aligndev")];
+    for (const entry of readEntries(sessionsDir)) {
+        if (entry.isDirectory() && !entry.name.startsWith("_")) {
+            sessionDirs.push(join(sessionsDir, entry.name, "_aligndev"));
+        }
+    }
+    const records = [];
+    for (const dir of sessionDirs) {
+        for (const entry of readEntries(dir)) {
+            if (!entry.isFile() || !entry.name.endsWith(".md"))
+                continue;
+            const path = join(dir, entry.name);
+            const completion = reconcileSessionFileOrSkip(path);
+            if (completion)
+                records.push({ path, frontmatter: completion.frontmatter });
+        }
+    }
+    return records;
+}
+export function findNewestSessionFile(dir) {
+    let newestName;
+    let newestStamp;
+    let newestSuffix = -1;
+    for (const entry of readEntries(dir)) {
+        if (!entry.isFile())
+            continue;
+        const match = /^(\d{8}-\d{6})(?:-(\d+))?\.md$/.exec(entry.name);
+        if (!match)
+            continue;
+        const stamp = match[1];
+        const suffix = Number(match[2] ?? 0);
+        if (newestStamp !== undefined && stamp < newestStamp)
+            continue;
+        if (stamp === newestStamp && suffix <= newestSuffix)
+            continue;
+        newestName = entry.name;
+        newestStamp = stamp;
+        newestSuffix = suffix;
+    }
+    return newestName === undefined ? undefined : join(dir, newestName);
+}
+function readEntries(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+}
+// A malformed file (e.g. missing its frontmatter block) must not block every future launch.
+function reconcileSessionFileOrSkip(path) {
+    try {
+        return reconcileSessionFile(path);
+    }
+    catch {
+        return;
+    }
+}
+// --- Frontmatter serialization (dependency-free, round-trips with parseFrontmatter) ---
+export function serializeFrontmatter(frontmatter) {
+    const lines = Object.entries(frontmatter).map(([key, value]) => `${key}: ${serializeValue(value)}`);
+    return `---\n${lines.join("\n")}\n---\n`;
+}
+function serializeValue(value) {
+    if (value === null)
+        return "";
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return needsQuote(value) ? JSON.stringify(value) : value;
+}
+function needsQuote(value) {
+    return value === "" || /[:"#]/.test(value) || value !== value.trim();
+}
+function splitSessionFile(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---\n/);
+    if (!match)
+        throw new Error("Session file is missing its frontmatter block.");
+    return { frontmatter: parseFrontmatter(match[1]), body: content.slice(match[0].length) };
+}
+export function parseFrontmatter(block) {
+    const map = {};
+    for (const line of block.split("\n")) {
+        const index = line.indexOf(":");
+        if (index === -1)
+            continue;
+        const key = line.slice(0, index).trim();
+        map[key] = parseValue(line.slice(index + 1).trim());
+    }
+    return {
+        status: map.status ?? "running",
+        agent: parseAgent(map.agent),
+        protocol: map.protocol ?? null,
+        ticket: map.ticket ?? null,
+        model: map.model ?? null,
+        sessionId: map.sessionId ?? null,
+        command: map.command ?? "",
+        meta: map.meta ?? null,
+        pid: parsePid(map.pid),
+        pidStartTime: map.pidStartTime ?? null,
+        cwd: map.cwd ?? null,
+        startedAt: map.startedAt ?? "",
+        endedAt: map.endedAt ?? null,
+        exitReason: map.exitReason ?? null,
+        contextTokens: parseCount(map.contextTokens),
+        contextCompacted: map.contextCompacted === "true",
+        contextTokensError: map.contextTokensError ?? null,
+    };
+}
+function parseAgent(raw) {
+    return raw === "claude" || raw === "codex" ? raw : null;
+}
+function parsePid(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    const pid = Number(raw);
+    return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
+}
+function parseCount(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    const count = Number(raw);
+    return Number.isSafeInteger(count) && count >= 0 ? count : null;
+}
+function parseValue(raw) {
+    if (raw === "")
+        return null;
+    if (!raw.startsWith('"'))
+        return raw;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        // A partially-written or hand-edited file may hold an unterminated/invalid quoted value; fall
+        // back to the raw text so the session file stays readable and sealable instead of crashing.
+        return raw;
+    }
+}
+// Local `YYYYMMDD-HHMMSS`.
+function formatStamp(now) {
+    const pad = (n) => String(n).padStart(2, "0");
+    const date = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`;
+    const time = `${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+    return `${date}-${time}`;
+}

package/dist/command-form.d.ts

@@ -0,0 +1,6 @@
+export interface CommandForms {
+    viaNpx: boolean;
+    aligndev: string;
+    alignfirst: string;
+}
+export declare function resolveCommandForms(env: NodeJS.ProcessEnv): CommandForms;

package/dist/command-form.js

@@ -0,0 +1,7 @@
+export function resolveCommandForms(env) {
+    const userAgent = env.npm_config_user_agent;
+    const viaNpx = userAgent !== undefined && userAgent !== "";
+    return viaNpx
+        ? { viaNpx, aligndev: "npx -y aligndev", alignfirst: "npx -y alignfirst" }
+        : { viaNpx, aligndev: "aligndev", alignfirst: "alignfirst" };
+}

package/dist/config.d.ts

@@ -0,0 +1,22 @@
+import { type CodingAgent } from "./code/coding-agent.js";
+export declare const PLATFORMS: readonly ["openclaw", "codingAgent"];
+export type Platform = (typeof PLATFORMS)[number];
+export interface AligndevConfig {
+    path: string;
+    platform: Platform;
+    projectsRoot?: ProjectsRoot;
+    code: CodeConfig;
+}
+export interface ProjectsRoot {
+    path: string;
+    written: string;
+}
+export interface CodeConfig {
+    agent: CodingAgent;
+    models?: string[];
+    skipPermissions: boolean;
+    unset: string[];
+}
+export declare function loadConfig(home: string): AligndevConfig | undefined;
+export declare function missingConfigMessage(home: string): string;
+export declare function requireProjectsRoot(config: AligndevConfig): ProjectsRoot;

package/dist/config.js

@@ -0,0 +1,72 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { type } from "arktype";
+import { CODING_AGENTS } from "./code/coding-agent.js";
+import { errorMessage } from "./errors.js";
+export const PLATFORMS = ["openclaw", "codingAgent"];
+const codeSchema = type({
+    "+": "reject",
+    agent: type.enumerated(...CODING_AGENTS),
+    "models?": "string[]",
+    "skipPermissions?": "boolean",
+    "unset?": "string[]",
+});
+const configSchema = type({
+    "+": "reject",
+    platform: type.enumerated(...PLATFORMS),
+    "projectsRoot?": "string > 0",
+    code: codeSchema,
+});
+// An absent file is a normal state: a machine where aligndev is not configured.
+export function loadConfig(home) {
+    const path = configPath(home);
+    if (!existsSync(path))
+        return;
+    const value = parseConfigFile(path);
+    return {
+        path,
+        platform: value.platform,
+        ...(value.projectsRoot === undefined
+            ? {}
+            : { projectsRoot: resolveProjectsRoot(value.projectsRoot, home, path) }),
+        code: {
+            agent: value.code.agent,
+            ...(value.code.models === undefined ? {} : { models: value.code.models }),
+            skipPermissions: value.code.skipPermissions ?? false,
+            unset: value.code.unset ?? [],
+        },
+    };
+}
+function configPath(home) {
+    return join(home, ".config", "alignfirst", "aligndev.config.json");
+}
+function parseConfigFile(path) {
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw invalidConfig(path, errorMessage(error));
+    }
+    const config = configSchema(value);
+    if (config instanceof type.errors)
+        throw invalidConfig(path, config.summary.split("\n", 1)[0]);
+    return config;
+}
+function invalidConfig(path, detail) {
+    return new Error(`Error: invalid aligndev config ${path}: ${detail}`);
+}
+function resolveProjectsRoot(written, home, path) {
+    if (written.startsWith("~/"))
+        return { path: join(home, written.slice(2)), written };
+    return { path: isAbsolute(written) ? written : resolve(dirname(path), written), written };
+}
+export function missingConfigMessage(home) {
+    return (`Error: no aligndev config at ${configPath(home)}. Create it with "platform" ` +
+        `(${PLATFORMS.join(" or ")}) and "code.agent" (${CODING_AGENTS.join(" or ")}).`);
+}
+export function requireProjectsRoot(config) {
+    if (config.projectsRoot !== undefined)
+        return config.projectsRoot;
+    throw new Error(`Error: projectsRoot is missing from the aligndev config ${config.path}.`);
+}

package/dist/errors.d.ts

@@ -0,0 +1,2 @@
+export declare function errorMessage(error: unknown): string;
+export declare function isNodeError(error: unknown): error is NodeJS.ErrnoException;

package/dist/errors.js

@@ -0,0 +1,6 @@
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}

package/dist/guide/code-guide.d.ts

@@ -0,0 +1,4 @@
+import type { CodingAgent } from "../code/coding-agent.js";
+import type { CommandForms } from "../command-form.js";
+import type { Platform } from "../config.js";
+export declare function renderCodeGuide(platform: Platform, agent: CodingAgent, models: readonly string[], forms: CommandForms): string;

package/dist/guide/code-guide.js

@@ -0,0 +1,17 @@
+import { renderGuideTemplate } from "./render-template.js";
+export function renderCodeGuide(platform, agent, models, forms) {
+    return renderGuideTemplate("code.md", platform, forms, {
+        AGENT: agent,
+        AUTH_COMMAND: agent === "claude" ? "`claude`, then `/login`" : "`codex login`",
+        PERMISSIONS: agent === "claude"
+            ? "Normal runs use `--permission-mode auto`, plus `--add-dir <companion>` when the project's AlignFirst files live in its companion directory. `code.skipPermissions: true` in the aligndev config selects `--dangerously-skip-permissions`"
+            : "Normal runs use `--sandbox workspace-write`, plus `--add-dir <companion>` when the project's AlignFirst files live in its companion directory. `code.skipPermissions: true` in the aligndev config selects `--dangerously-bypass-approvals-and-sandbox`",
+        MODELS: models.map((model) => `\`${model}\``).join(", "),
+        ALIGNFIRST_SETUP: forms.viaNpx
+            ? "The project must be prepared for AlignFirst. `npx -y aligndev` runs the `alignfirst` CLI through `npx`."
+            : "The project must be prepared for AlignFirst, with the `alignfirst` CLI installed (`npm install -g alignfirst`).",
+        ALIGNFIRST_USE: forms.viaNpx
+            ? "`npx -y aligndev code` runs the `alignfirst` CLI through `npx`, and so does the coder: it runs `npx -y alignfirst guide <protocol>` in the project."
+            : "`aligndev code` requires the `alignfirst` CLI on `PATH`. The coder runs `alignfirst guide <protocol>` in the project, so the protocols come from the installed CLI.",
+    });
+}

package/dist/guide/guide-cli.d.ts

@@ -0,0 +1,3 @@
+import { type AligndevConfig } from "../config.js";
+import { type ProjectsCallerContext } from "../project/project-cli.js";
+export declare function runGuide(tokens: string[], config: AligndevConfig, ctx: ProjectsCallerContext): number;

package/dist/guide/guide-cli.js

@@ -0,0 +1,81 @@
+import { parseArgs } from "node:util";
+import { resolveModels } from "../code/models.js";
+import { PLATFORMS, requireProjectsRoot } from "../config.js";
+import { errorMessage } from "../errors.js";
+import { renderProjectsGuideForRoot } from "../project/project-cli.js";
+import { renderCodeGuide } from "./code-guide.js";
+import { renderGuideTemplate } from "./render-template.js";
+import { PLAYBOOK_DISPATCHER, PLAYBOOK_TOPICS } from "./topics.js";
+export function runGuide(tokens, config, ctx) {
+    try {
+        const args = parseGuideArgs(tokens);
+        ctx.stdout.write(args.help ? renderUsage(ctx.forms) : `${renderTopic(args, config, ctx)}\n`);
+        return 0;
+    }
+    catch (error) {
+        ctx.stderr.write(`${errorMessage(error)}\n`);
+        return 1;
+    }
+}
+function parseGuideArgs(tokens) {
+    const { values, positionals } = parseArgs({
+        args: tokens,
+        options: {
+            root: { type: "string" },
+            help: { type: "boolean", short: "h", default: false },
+        },
+        strict: true,
+        allowPositionals: true,
+    });
+    if (positionals.length > 1)
+        throw new Error("Error: `aligndev guide` takes at most one topic.");
+    const [topic] = positionals;
+    if (values.root !== undefined && topic !== "project") {
+        throw new Error("Error: --root is valid only with `aligndev guide project`.");
+    }
+    return { topic, root: values.root, help: values.help };
+}
+function renderUsage(forms) {
+    const playbookTopics = PLATFORMS.map((platform) => `  ${platform}: ${PLAYBOOK_TOPICS[platform].join(", ")}`);
+    return `Usage:
+  ${forms.aligndev} guide [<topic>] [--root <path>]
+  ${forms.aligndev} guide --help
+
+Without a topic, prints the playbook of the platform set in the aligndev config.
+
+Topics:
+  code        The delegation guide for \`${forms.aligndev} code\`.
+  project     The projects guide, openclaw only. --root overrides projectsRoot in the aligndev config.
+
+Playbook topics, by platform:
+${playbookTopics.join("\n")}
+`;
+}
+function renderTopic(args, config, ctx) {
+    if (args.topic === "code")
+        return renderCodeTopic(config, ctx.forms);
+    if (args.topic === "project" && config.platform === "openclaw") {
+        return renderProjectsGuideForRoot({ ...ctx, projectsRoot: config.projectsRoot }, args.root);
+    }
+    return renderPlaybookTopic(args.topic, config, ctx.forms);
+}
+function renderCodeTopic(config, forms) {
+    const { code } = config;
+    const models = resolveModels(code.agent, code.models);
+    return renderCodeGuide(config.platform, code.agent, models, forms);
+}
+function renderPlaybookTopic(topic, config, forms) {
+    if (topic !== undefined)
+        assertPlaybookTopic(topic, config.platform);
+    const values = config.platform === "openclaw"
+        ? { PROJECTS_ROOT: requireProjectsRoot(config).written }
+        : undefined;
+    return renderGuideTemplate(`playbook/${topic ?? PLAYBOOK_DISPATCHER}.md`, config.platform, forms, values);
+}
+function assertPlaybookTopic(topic, platform) {
+    const topics = PLAYBOOK_TOPICS[platform];
+    if (topics.includes(topic))
+        return;
+    const specialTopics = platform === "openclaw" ? ["code", "project"] : ["code"];
+    throw new Error(`Error: unknown guide topic "${topic}". Topics: ${[...specialTopics, ...topics].join(", ")}.`);
+}

package/dist/guide/render-template.d.ts

@@ -0,0 +1,4 @@
+import type { CommandForms } from "../command-form.js";
+import { type Platform } from "../config.js";
+export declare function renderGuideTemplate(name: string, platform: Platform, forms: CommandForms, values?: Readonly<Record<string, string>>): string;
+export declare function renderPlatformBlocks(text: string, platform: Platform, templateName: string): string;

package/dist/guide/render-template.js

@@ -0,0 +1,62 @@
+import { PLATFORMS } from "../config.js";
+import { readTemplate } from "../templates.js";
+const MARKER = /^\{\{([#/])([A-Za-z]+)\}\}$/;
+// Renders `templates/guide/<name>`: the platform blocks first, then the placeholders — the command
+// forms and every key of `values`.
+export function renderGuideTemplate(name, platform, forms, values = {}) {
+    const placeholders = {
+        ALIGNDEV: forms.aligndev,
+        ALIGNFIRST: forms.alignfirst,
+        ...values,
+    };
+    let text = renderPlatformBlocks(readTemplate(`guide/${name}`), platform, name);
+    for (const [key, value] of Object.entries(placeholders)) {
+        text = text.replaceAll(`{{${key}}}`, value);
+    }
+    return text.trimEnd();
+}
+// A block is `{{#<platform>}}` … `{{/<platform>}}`, each marker alone on its line. The active
+// platform's blocks keep their content; the others are removed. Blocks do not nest. The runs of
+// empty lines that removed blocks leave collapse to one.
+export function renderPlatformBlocks(text, platform, templateName) {
+    const kept = [];
+    let open;
+    for (const [index, line] of text.split("\n").entries()) {
+        const marker = MARKER.exec(line);
+        if (marker === null) {
+            if (open === undefined || open.platform === platform)
+                kept.push(line);
+            continue;
+        }
+        const [, kind, name] = marker;
+        const lineNumber = index + 1;
+        if (!isPlatform(name)) {
+            throw blockError(templateName, lineNumber, `unknown platform "${name}"`);
+        }
+        if (kind === "#") {
+            if (open !== undefined) {
+                throw blockError(templateName, lineNumber, `block "${name}" nested in "${open.platform}"`);
+            }
+            open = { platform: name, line: lineNumber };
+        }
+        else {
+            if (open?.platform !== name) {
+                throw blockError(templateName, lineNumber, `closing marker "${name}" without its block`);
+            }
+            open = undefined;
+        }
+    }
+    if (open !== undefined) {
+        throw blockError(templateName, open.line, `block "${open.platform}" is not closed`);
+    }
+    return collapseEmptyLines(kept).join("\n");
+}
+function isPlatform(name) {
+    return PLATFORMS.includes(name);
+}
+function blockError(templateName, line, detail) {
+    return new Error(`Error: template ${templateName}, line ${line}: ${detail}.`);
+}
+function collapseEmptyLines(lines) {
+    return lines.filter((line, index) => line !== "" || lines[index - 1] !== "");
+}

package/dist/guide/topics.d.ts

@@ -0,0 +1,3 @@
+import type { Platform } from "../config.js";
+export declare const PLAYBOOK_DISPATCHER = "playbook";
+export declare const PLAYBOOK_TOPICS: Record<Platform, readonly string[]>;

package/dist/guide/topics.js

@@ -0,0 +1,16 @@
+// The template rendered by `aligndev guide` without a topic.
+export const PLAYBOOK_DISPATCHER = "playbook";
+// The playbook topics each platform serves. Every topic is one file of `templates/guide/playbook/`,
+// shared by the platforms through platform blocks.
+export const PLAYBOOK_TOPICS = {
+    openclaw: [
+        "channel-handling",
+        "working-session",
+        "project-workspace-setup",
+        "project-lifecycle",
+        "consultation",
+        "slack-message-tool",
+        "discord-message-tool",
+    ],
+    codingAgent: ["working-session", "project-workspace-setup", "consultation"],
+};

package/dist/output.d.ts

@@ -0,0 +1,3 @@
+export interface Output {
+    write(text: string): void;
+}

package/dist/output.js

@@ -0,0 +1 @@
+export {};

package/dist/project/discovery.d.ts

@@ -0,0 +1,42 @@
+import { type ProjectReport } from "./layout.js";
+import { type MarkerPortRange, type PortRange, type ProjectsMarker } from "./markers.js";
+export interface ProjectInventory {
+    root: string;
+    directories: ProjectsDirectory[];
+    projects: DiscoveredProject[];
+    issues: InventoryIssue[];
+}
+export interface ProjectsDirectory {
+    path: string;
+    description?: string;
+    portRanges?: MarkerPortRange[];
+    others: string[];
+}
+export interface DiscoveredProject {
+    name: string;
+    path: string;
+    directory: string;
+    description: ProjectReport;
+    portRange?: PortRange;
+    portRangeCode?: string;
+    workspaces: string[];
+}
+export interface InventoryIssue {
+    path: string;
+    message: string;
+    conflict?: PortConflict;
+}
+export interface PortConflict {
+    left: ProjectPortClaim;
+    right: ProjectPortClaim;
+}
+interface ProjectPortClaim {
+    path: string;
+    portRange: PortRange;
+}
+export interface InventoryContext {
+    env: NodeJS.ProcessEnv;
+    alignfirstCommand: string[];
+}
+export declare function buildInventory(root: string, marker: ProjectsMarker, ctx: InventoryContext): ProjectInventory;
+export {};