aligndev 0.0.0 → 0.19.0

package/README.md

@@ -1,3 +1,168 @@
 # aligndev
 
-The AlignFirst Dev Kit CLI. This placeholder release reserves the name; use a later version.
+The AlignFirst Dev Kit CLI. It carries the assistant's playbook, runs a coding agent through [AlignFirst](https://github.com/paleo/alignfirst) protocols, and keeps the inventory of the host's projects and their port ranges. The assistant is an OpenClaw bot, or a coding agent working on one project.
+
+Run `aligndev` through `npx` (`npx -y aligndev …`), or install it with `npm install -g aligndev`. Through `npx`, it runs `alignfirst` through `npx` too, and its help and guides print both commands in that form. A global `aligndev` needs the `alignfirst` CLI on `PATH`: `npm install -g alignfirst`.
+
+Supported systems: Linux and macOS, and Windows through WSL.
+
+## Commands
+
+```sh
+aligndev code <command> [<options>]      # run a coding agent through AlignFirst protocols
+aligndev project <command> [<options>]   # list projects, check the inventory, claim port ranges
+aligndev guide [<topic>]                 # print the playbook and the guides
+aligndev --help
+aligndev --version
+```
+
+Each command prints its own usage with `--help`.
+
+### `aligndev code`
+
+```sh
+aligndev code new --protocol spec --ticket AB-123 --message "Feature description"
+aligndev code resume <sessionId> --protocol plan
+aligndev code new --message "Execute the plan: .plans/AB-123/A2-plan.md"
+aligndev code new --protocol aad --no-ticket --message "Task description"
+aligndev code new --ticket AB-123 --catchup --protocol aad --message-file message.md
+aligndev code status .plans/AB-123/_aligndev/20260829-135529.md
+aligndev code quota
+```
+
+The coding agent `aligndev code` launches is **the coder**. Run `aligndev code` from the root of the target project. The project must have a `.plans/` directory, in its repository or in its companion directory.
+
+`aligndev code` reads the project's layout from `alignfirst config --json`. Session files go under its `_aligndev` location: `<ticket>/_aligndev/` or `_aligndev/`, below the project's `.plans/` unless the companion holds a separate tree. When some of the project's AlignFirst files exist in its companion, the normal permission modes make the companion writable for the coder (`--add-dir`), and a new session's prompt starts with the `alignfirst context` output.
+
+A new protocol session needs a ticket. `--no-ticket` reserves the next side ticket through `alignfirst ticket --side` and passes it to the coder.
+
+`--catchup` loads the ticket's history (through `alignfirst ticket --catchup`) before the protocol and message. Alone, it returns a short synthesis.
+
+`--message-file <path>` reads the message from a UTF-8 file, or from stdin with `-`. The prompt reaches the coder through stdin.
+
+`aligndev code status` reconciles and shows a run's durable status. It accepts a session file under `_aligndev/` or `<ticket>/_aligndev/` of the `_aligndev` location, or selects the newest run with `--ticket <id>`, `--no-ticket` or `--meta <key>`. If a recorded process is gone, it seals the session file as `status: failed`, `exitReason: terminated`. Linux records also store the process start time to detect pid reuse. Its `contextTokens` line reports what the run left in the coder's context window; a resumed session keeps growing across runs.
+
+`aligndev code quota` shows the selected coding agent's account limits, consumed percentages, and reset times. It works outside a project.
+
+### `aligndev project`
+
+```sh
+aligndev project list [--json] [--root <path>]
+aligndev project doctor [--root <path>]
+aligndev project status <path> [--json] [--root <path>]
+aligndev project init [--root <path>] [--description <text>] [--port-range [<code>=]<first>-<last>]...
+aligndev project free-ports --size <n> [--range <code>] [--json] [--root <path>]
+```
+
+A projects directory groups projects and optional nested projects directories. Its `.alignfirst-projects.json` marker holds an optional description and port ranges. A direct child that is a Git main worktree is a project; linked Git worktrees are listed as its workspaces. A child outside Git with a root `.alignfirst.json` is an inventory issue. `list --json` and `status` report each project's companion directory and the location of its AlignFirst files. Two projects sharing one companion directory is an inventory issue.
+
+```json
+{
+  "description": "Every project is a direct child of ~/projects.",
+  "portRanges": [
+    { "first": 28000, "last": 28599, "description": "Web projects, exposed through the gateway." },
+    { "code": "local", "first": 29000, "last": 29199, "description": "Desktop apps, never exposed." }
+  ]
+}
+```
+
+`--root` defaults to `projectsRoot` in the config, then to the working directory. `doctor` is a read-only health gate: it succeeds only when discovery completes with no inventory issue.
+
+An older marker carrying `"portRange": { ... }` is rejected; replace the key with `"portRanges": [{ ... }]`. Project configuration in `.alignfirst.json` keeps its singular `portRange` key.
+
+### `aligndev guide`
+
+```sh
+aligndev guide [<topic>] [--root <path>]
+```
+
+Each topic renders the variant of the configured `platform`.
+
+| Topic | Output | Platforms |
+|-------|--------|-----------|
+| (none) | The playbook dispatcher. | both |
+| `working-session` | The work procedure: a thread under OpenClaw, the conversation for a coding agent. | both |
+| `project-workspace-setup`, `consultation` | Runbooks. | both |
+| `code` | The delegation guide. | both |
+| `channel-handling` | The channel and DM procedure. | `openclaw` |
+| `project-lifecycle` | The runbook to create, onboard or remove a project. | `openclaw` |
+| `slack-message-tool`, `discord-message-tool` | Extended `message` references. | `openclaw` |
+| `project` | The projects guide, followed by the directory sections when the root carries a marker. `--root` overrides `projectsRoot`. | `openclaw` |
+
+Under `openclaw`, the playbook topics require `projectsRoot`.
+
+## Configuration
+
+`aligndev` reads one file, `~/.config/alignfirst/aligndev.config.json`. The path is fixed: no environment variable overrides it. `aligndev code` and `aligndev guide` require it, `--help` included. Without it, they fail with an error naming the path and the required keys. `aligndev project`, `aligndev --help` and `aligndev --version` run without it.
+
+```json
+{
+  "platform": "openclaw",
+  "projectsRoot": "~/projects",
+  "code": {
+    "agent": "claude",
+    "models": ["opus", "sonnet"],
+    "skipPermissions": false,
+    "unset": ["ANTHROPIC_API_KEY"]
+  }
+}
+```
+
+A coding agent acting as the assistant needs only the required keys:
+
+```json
+{
+  "platform": "codingAgent",
+  "code": { "agent": "codex" }
+}
+```
+
+- `platform` — required. Selects the variant of every `aligndev guide` topic: `openclaw` for an OpenClaw assistant, `codingAgent` for a coding agent acting as the assistant.
+- `projectsRoot` — the default projects directory of `aligndev project` and `aligndev guide project`. Required by the `openclaw` playbook. `~/` expands to the home directory; a relative path resolves against the config file's directory.
+- `code.agent` — required. The coder: `claude` or `codex`.
+- `code.models` — replaces the selected agent's accepted models.
+- `code.skipPermissions` — `true` selects each CLI's dangerous permission-bypass flag. Default: `false`.
+- `code.unset` — environment variables stripped from the coder's environment. `aligndev code` always strips the assistant session's identity variables first (`CLAUDECODE`, `CLAUDE_CODE_SESSION_ID`, `CODEX_THREAD_ID`, …), whatever the agent.
+
+Unknown keys are rejected. An unreadable file, invalid JSON or an invalid value fails every command that loads the config, with an error naming the file.
+
+Companion directories are declared in `~/.config/alignfirst/companions.json`, which the `alignfirst` CLI reads for both tools. See [its README](https://github.com/paleo/alignfirst/tree/main/packages/alignfirst#companion-directories).
+
+## Execution model
+
+`aligndev code` runs the coder as a direct **foreground** child of its own process. It streams a live transcript to stdout and to a per-run session file, whose frontmatter status goes from `running` to `succeeded` or `failed`, and blocks until the coder exits. It never backgrounds or detaches itself.
+
+Coding runs can be very long, so the caller always runs `aligndev code` as a background task and owns the backgrounding, as `aligndev guide code` prescribes:
+
+- Under OpenClaw, the assistant invokes it through the `exec` tool with `background: true` and `timeoutSeconds: 0`, and chains `openclaw system event --mode now --session-key <key>` onto the command.
+- A coding-agent assistant starts it with its own background-execution facility, with no time limit, and outside its sandbox. When the agent wakes the session as the command exits, as Claude Code does, the assistant handles the completion on that wake. Otherwise, the assistant checks its pending runs at the start of the next user turn.
+
+The completion turn locates the session file with `aligndev code status` and reads the result. The session file is the durable result handoff: frontmatter `sessionId` and status, and the `---- Result ----` block.
+
+If `aligndev code` is terminated, its signal handlers seal the session file (`status: failed`, `exitReason: terminated`), then send `SIGTERM` to the coder. After a short grace period, a `SIGKILL` guarantees no orphan is left behind. Only a `SIGKILL` of `aligndev` itself can leave a stale `running` status, which the next `status` call seals.
+
+When the coding agent's session on the host is missing or expired, `aligndev code` detects the authentication failure in its stream, seals the session file with `exitReason: auth_required`, and exits `2` with a one-line stderr message.
+
+## Coding agents
+
+Install the selected CLI and authenticate it on the host: run `claude`, then `/login`, for Claude Code; run `codex login` for Codex.
+
+Normal runs use Claude's `--permission-mode auto` or Codex's `--sandbox workspace-write`.
+
+Claude's default model list is `fable`, `opus`, `sonnet`, `haiku`. Codex's is `astra`, `sol`, `terra`, `luna`; `aligndev code` resolves a selected Codex alias against `codex debug models --bundled`. Set `code.models` to narrow the list or to advertise an explicit Codex slug such as `gpt-5.6-terra`.
+
+Session files record `agent`. A session resumes only with the same selected agent. Agentless legacy sessions stay readable but require a new session.
+
+## The `aligndev` skill
+
+The `aligndev` agent skill makes a Claude Code or Codex session the assistant of the project it runs in. Invoked as `/aligndev` in Claude Code, or `$aligndev` in Codex, it loads the playbook through `npx -y aligndev guide`, which needs `platform: "codingAgent"` in the config. Install it:
+
+```sh
+npx skills add https://github.com/paleo/alignfirst --global --skill aligndev
+```
+
+The setup guide's [coding-agent assistant reference](https://github.com/paleo/alignfirst/blob/main/skills/alignfirst-setup-guide/references/coding-agent-assistant.md) covers the project, the configuration and the sandbox.
+
+## Port claims
+
+Run `aligndev project free-ports --size <n>` with the block size required by the project's workspace scheme: `perWorkspace × maxWorkspaces`. A marker entry without a code is the default range. Pass `--range <code>` to select a coded range. The setup guide writes the returned block as `portRange` in the project's `.alignfirst.json`.

package/bin/aligndev.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "../dist/cli.js";
+process.exit(await main());

package/dist/alignfirst-cli.d.ts

@@ -0,0 +1,10 @@
+export interface AlignfirstResult {
+    status: number;
+    stdout: string;
+    stderr: string;
+}
+export declare function runAlignfirst(command: string[], args: string[], cwd: string, env?: NodeJS.ProcessEnv): AlignfirstResult;
+export declare function reserveSideTicket(command: string[], cwd: string, env: NodeJS.ProcessEnv): string;
+export declare function openTicket(command: string[], cwd: string, ticket: string, env: NodeJS.ProcessEnv): void;
+export declare function loadCatchup(command: string[], cwd: string, ticket: string, env: NodeJS.ProcessEnv): string;
+export declare function loadContext(command: string[], cwd: string, env: NodeJS.ProcessEnv): string;

package/dist/alignfirst-cli.js

@@ -0,0 +1,56 @@
+import { spawnSync } from "node:child_process";
+export function runAlignfirst(command, args, cwd, env = process.env) {
+    const result = spawnSync(command[0], [...command.slice(1), ...args], {
+        cwd,
+        env,
+        encoding: "utf8",
+    });
+    if (result.error && isErrnoException(result.error) && result.error.code === "ENOENT") {
+        throw new Error("alignfirst is not installed. Install it globally (`npm install -g alignfirst`), or run " +
+            "aligndev through npx (`npx -y aligndev`).");
+    }
+    if (result.error)
+        throw result.error;
+    return {
+        status: result.status ?? 1,
+        stdout: result.stdout,
+        stderr: result.stderr,
+    };
+}
+export function reserveSideTicket(command, cwd, env) {
+    const result = runAlignfirst(command, ["ticket", "--side", "--json"], cwd, env);
+    if (result.status !== 0) {
+        throw new Error(result.stderr.trim() || "alignfirst ticket --side failed");
+    }
+    const report = JSON.parse(result.stdout);
+    if (!isRecord(report) || typeof report.TICKET_ID !== "string") {
+        throw new Error("alignfirst ticket --side returned an invalid JSON report");
+    }
+    return report.TICKET_ID;
+}
+// Creates or restores the ticket's directories, as `alignfirst ticket <id>` does for a developer.
+export function openTicket(command, cwd, ticket, env) {
+    const result = runAlignfirst(command, ["ticket", ticket, "--json"], cwd, env);
+    if (result.status !== 0)
+        throw new Error(result.stderr.trim() || "alignfirst ticket failed");
+}
+export function loadCatchup(command, cwd, ticket, env) {
+    const result = runAlignfirst(command, ["ticket", ticket, "--catchup"], cwd, env);
+    if (result.status !== 0) {
+        throw new Error(result.stderr.trim() || "alignfirst ticket --catchup failed");
+    }
+    return result.stdout;
+}
+export function loadContext(command, cwd, env) {
+    const result = runAlignfirst(command, ["context"], cwd, env);
+    if (result.status !== 0) {
+        throw new Error(result.stderr.trim() || "alignfirst context failed");
+    }
+    return result.stdout;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isErrnoException(error) {
+    return "code" in error;
+}

package/dist/cli.d.ts

@@ -0,0 +1,15 @@
+import { type ExecutableModelResolver } from "./code/models.js";
+import { type QuotaReader } from "./code/quota.js";
+import type { Output } from "./output.js";
+export interface MainOptions {
+    argv?: string[];
+    stdout?: Output;
+    stderr?: Output;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    alignfirstCommand?: string[];
+    modelResolver?: ExecutableModelResolver;
+    quotaReader?: QuotaReader;
+}
+export declare function main(options?: MainOptions): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,95 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { runCode } from "./code/code-cli.js";
+import { CODING_AGENTS } from "./code/coding-agent.js";
+import { resolveExecutableModel } from "./code/models.js";
+import { readQuota } from "./code/quota.js";
+import { resolveCommandForms } from "./command-form.js";
+import { loadConfig, missingConfigMessage, PLATFORMS } from "./config.js";
+import { errorMessage } from "./errors.js";
+import { runGuide } from "./guide/guide-cli.js";
+import { runProject } from "./project/project-cli.js";
+export async function main(options) {
+    const ctx = resolveContext(options);
+    const [command, ...tokens] = (options?.argv ?? process.argv).slice(2);
+    if (command === "--help" || command === "-h") {
+        ctx.stdout.write(renderHelp(ctx.forms.aligndev));
+        return 0;
+    }
+    if (command === "--version" || command === "-v") {
+        ctx.stdout.write(`${readPackageVersion()}\n`);
+        return 0;
+    }
+    if (command !== "code" && command !== "project" && command !== "guide") {
+        const error = command === undefined ? "Error: no command given." : `Error: unknown command "${command}".`;
+        ctx.stderr.write(`${error}\n\n${renderHelp(ctx.forms.aligndev)}`);
+        return 1;
+    }
+    let config;
+    try {
+        config = loadConfig(ctx.home);
+    }
+    catch (error) {
+        ctx.stderr.write(`${errorMessage(error)}\n`);
+        return 1;
+    }
+    if (command === "project")
+        return runProject(tokens, config, ctx);
+    if (config === undefined) {
+        ctx.stderr.write(`${missingConfigMessage(ctx.home)}\n`);
+        return 1;
+    }
+    if (command === "code")
+        return runCode(tokens, config, ctx);
+    return runGuide(tokens, config, ctx);
+}
+function renderHelp(aligndev) {
+    const usage = renderUsageRows([
+        [`${aligndev} code <command> [<options>]`, "Run a coding agent through AlignFirst protocols."],
+        [
+            `${aligndev} project <command> [<options>]`,
+            "List projects, check their inventory, claim port ranges.",
+        ],
+        [`${aligndev} guide [<topic>]`, "Print the assistant's playbook and guides."],
+        [`${aligndev} -h, --help`],
+        [`${aligndev} -v, --version`],
+    ]);
+    return `aligndev — the AlignFirst Dev Kit CLI.
+
+Usage:
+${usage}
+
+Run \`${aligndev} <command> --help\` for the usage of a command.
+
+Config: ~/.config/alignfirst/aligndev.config.json, with "platform" (${PLATFORMS.join(" or ")}) and
+"code.agent" (${CODING_AGENTS.join(" or ")}). \`${aligndev} code\` and \`${aligndev} guide\` require it.
+`;
+}
+// Each row is a command, optionally followed by its description in an aligned column.
+function renderUsageRows(rows) {
+    const width = Math.max(...rows.map(([command]) => command.length)) + 3;
+    return rows
+        .map(([command, description]) => description === undefined ? `  ${command}` : `  ${command.padEnd(width)}${description}`)
+        .join("\n");
+}
+function resolveContext(options) {
+    const env = options?.env ?? process.env;
+    const forms = resolveCommandForms(env);
+    return {
+        cwd: options?.cwd ?? process.cwd(),
+        env,
+        home: options?.home ?? env.HOME ?? env.USERPROFILE ?? homedir(),
+        stdout: options?.stdout ?? process.stdout,
+        stderr: options?.stderr ?? process.stderr,
+        forms,
+        alignfirstCommand: options?.alignfirstCommand ?? forms.alignfirst.split(" "),
+        modelResolver: options?.modelResolver ?? resolveExecutableModel,
+        quotaReader: options?.quotaReader ?? readQuota,
+    };
+}
+function readPackageVersion() {
+    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    if (pkg.version === undefined)
+        throw new Error("aligndev: package.json is missing 'version'");
+    return pkg.version;
+}

package/dist/code/claude-agent.d.ts

@@ -0,0 +1,14 @@
+import type { AgentAdapter, AgentProtocolState, RunConfig } from "./run-agent.js";
+export declare function createClaudeAdapter(): AgentAdapter;
+export declare function buildClaudeArgs(config: RunConfig): string[];
+export declare function createClaudeState(): AgentProtocolState;
+export declare function interpretClaudeLine(line: string, state: AgentProtocolState): string | undefined;
+export declare function assessClaudeState(state: AgentProtocolState): {
+    succeeded: boolean;
+    sessionId: string | undefined;
+    result: string | undefined;
+    error: string | undefined;
+    authEvidence: boolean;
+    contextTokens: number | undefined;
+    contextCompacted: boolean;
+};

package/dist/code/claude-agent.js

@@ -0,0 +1,168 @@
+import { isCompacted } from "./run-agent.js";
+export function createClaudeAdapter() {
+    return {
+        executable: "claude",
+        buildArgs: buildClaudeArgs,
+        createState: createClaudeState,
+        interpretLine: interpretClaudeLine,
+        assess: assessClaudeState,
+        isAuthenticationError: () => false,
+        authenticationMessage: claudeAuthenticationMessage,
+    };
+}
+export function buildClaudeArgs(config) {
+    const args = ["-p", "--output-format", "stream-json", "--verbose"];
+    if (config.skipPermissions) {
+        args.push("--dangerously-skip-permissions");
+    }
+    else {
+        args.push("--permission-mode", "auto");
+    }
+    // `--add-dir` is variadic: only options may follow it. The prompt goes through stdin.
+    for (const dir of config.additionalDirectories)
+        args.push("--add-dir", dir);
+    if (config.resume !== undefined)
+        args.push("--resume", config.resume);
+    if (config.executableModel !== undefined)
+        args.push("--model", config.executableModel);
+    return args;
+}
+export function createClaudeState() {
+    return {
+        protocolComplete: false,
+        protocolFailed: false,
+        authEvidence: false,
+    };
+}
+export function interpretClaudeLine(line, state) {
+    const event = parseEventLine(line);
+    if (!isRecord(event))
+        return;
+    captureSessionId(event, state);
+    if (event.error === "authentication_failed")
+        state.authEvidence = true;
+    switch (event.type) {
+        case "system":
+            return event.subtype === "init" ? `[init] session ${asString(event.session_id)}` : undefined;
+        case "assistant":
+            captureContextTokens(event, state);
+            return renderMessageContent(event);
+        case "user":
+            return renderMessageContent(event);
+        case "result":
+            state.protocolComplete = true;
+            state.protocolFailed = event.is_error === true;
+            state.result = asString(event.result);
+            if (state.protocolFailed)
+                state.failure = state.result;
+            return;
+        case "unparsed":
+            return asString(event.raw);
+        default:
+            return;
+    }
+}
+export function assessClaudeState(state) {
+    return {
+        succeeded: state.protocolComplete && !state.protocolFailed && state.result !== undefined,
+        sessionId: state.sessionId,
+        result: state.result,
+        error: state.failure,
+        authEvidence: state.authEvidence,
+        contextTokens: state.contextTokens,
+        contextCompacted: isCompacted(state),
+    };
+}
+// What the newest assistant response holds in the context window. Claude reports cache reads and
+// writes beside `input_tokens`, so the occupancy is their sum plus the response itself. A subagent
+// message carries `parent_tool_use_id` and measures its own context, not the main conversation's.
+function captureContextTokens(event, state) {
+    if (event.parent_tool_use_id != null)
+        return;
+    const message = event.message;
+    if (!isRecord(message) || !isRecord(message.usage))
+        return;
+    const usage = message.usage;
+    const total = asCount(usage.input_tokens) +
+        asCount(usage.cache_creation_input_tokens) +
+        asCount(usage.cache_read_input_tokens) +
+        asCount(usage.output_tokens);
+    if (total === 0)
+        return;
+    state.contextTokens = total;
+    state.peakContextTokens = Math.max(state.peakContextTokens ?? 0, total);
+}
+function parseEventLine(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return { type: "unparsed", raw: line };
+    }
+}
+function captureSessionId(event, state) {
+    const id = asString(event.session_id);
+    if (id !== undefined && id !== "")
+        state.sessionId = id;
+}
+function renderMessageContent(event) {
+    const message = event.message;
+    if (!isRecord(message) || !Array.isArray(message.content))
+        return;
+    const parts = [];
+    for (const block of message.content) {
+        const rendered = renderBlock(block);
+        if (rendered !== undefined && rendered !== "")
+            parts.push(rendered);
+    }
+    return parts.length > 0 ? parts.join("\n") : undefined;
+}
+function renderBlock(block) {
+    if (!isRecord(block))
+        return;
+    switch (block.type) {
+        case "text":
+            return asString(block.text);
+        case "tool_use":
+            return `[tool: ${asString(block.name) ?? "?"}] ${compactJson(block.input)}`;
+        case "tool_result":
+            return `[tool result] ${truncate(renderToolResult(block.content), 500)}`;
+        default:
+            return;
+    }
+}
+function renderToolResult(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content.map((block) => (isRecord(block) ? (asString(block.text) ?? "") : "")).join("");
+    }
+    return compactJson(content);
+}
+function claudeAuthenticationMessage(detail) {
+    const base = "Coding agent not authenticated (authentication_failed): the host session is missing, " +
+        "expired, or rejected. An administrator must re-login on the host (run `claude`, then " +
+        "`/login`) before `aligndev code` can run again.";
+    const reason = detail?.trim();
+    return reason === undefined || reason === "" ? base : `${base}\n\n${reason}`;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function asString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function asCount(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+function compactJson(value) {
+    try {
+        return truncate(JSON.stringify(value) ?? "", 500);
+    }
+    catch {
+        return "";
+    }
+}
+function truncate(text, max) {
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+}

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

@@ -0,0 +1,72 @@
+import type { CommandForms } from "../command-form.js";
+import type { AligndevConfig, CodeConfig } from "../config.js";
+import type { Output } from "../output.js";
+import { type ProjectReport } from "../project/layout.js";
+import { type CodingAgent } from "./coding-agent.js";
+import { type ExecutableModelResolver } from "./models.js";
+import type { QuotaReader } from "./quota.js";
+import { type RunConfig } from "./run-agent.js";
+import { type SessionRecord } from "./session-file.js";
+export interface CodeContext {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    stdout: Output;
+    stderr: Output;
+    forms: CommandForms;
+    alignfirstCommand: string[];
+    modelResolver: ExecutableModelResolver;
+    quotaReader: QuotaReader;
+}
+export type CodeCommand = {
+    kind: "help";
+} | {
+    kind: "status";
+    target: StatusTarget;
+} | {
+    kind: "quota";
+} | {
+    kind: "session";
+    args: SessionArgs;
+};
+export type StatusTarget = {
+    kind: "file";
+    sessionFile: string;
+} | {
+    kind: "ticket";
+    ticket: string;
+} | {
+    kind: "noTicket";
+} | {
+    kind: "meta";
+    meta: string;
+};
+export interface SessionArgs {
+    resume?: string;
+    ticket?: string;
+    noTicket: boolean;
+    protocol?: string;
+    catchup?: boolean;
+    messageFile?: string;
+    message?: string;
+    model?: string;
+    meta?: string;
+}
+export declare function runCode(tokens: string[], config: AligndevConfig, ctx: CodeContext): Promise<number>;
+export declare function parseCodeArgs(tokens: string[], aligndev: string): CodeCommand;
+export declare function validateSessionArgs(args: SessionArgs, models: readonly string[]): string | undefined;
+export declare function checkLaunchGuards(args: SessionArgs, agent: CodingAgent, realCwd: string, records: SessionRecord[]): string | undefined;
+export declare function resolveTicket(args: SessionArgs, records: SessionRecord[]): string | undefined;
+export interface RunInput {
+    args: SessionArgs;
+    code: CodeConfig;
+    report: ProjectReport;
+    ticket: string | undefined;
+    cwd: string;
+    sessionFilePath: string;
+    env: NodeJS.ProcessEnv;
+    executableModel: string | undefined;
+    catchupContent?: string;
+    contextContent?: string;
+    alignfirst: string;
+}
+export declare function buildRunConfig(input: RunInput): RunConfig;