A local-first multi-agent app development platform, built on PenguinHarness
/**
* `penguin org` — company mode: a thin client over the organization API. Every
* subcommand addresses one organization of one Project. The organization's files under
* the Project directory (the employee tree, the desks ledger, calendar, tickets,
* channels) stay the single source of truth; each command reads a projection of them or
* writes through the route that edits them, with the same validated-writer contract
* `schedule` has — API errors surface verbatim, so an agent gets synchronous validation.
*
* penguin org ls [--project-id <id>] [--json] [--server <url>]
* penguin org create --org-id <id> --mission <s> [--name <s>] [--ceo-budget <usd>]
* penguin org show | chart
* penguin org hire (--agent-id <id> | --new-agent <id> [--name] [--description] [--skills <a,b>])
* --title <s> --reports-to <agent_id> [--workspace <path>] [--budget <usd>] [--duties <s>]
* penguin org employee set <agent_id> [--title] [--reports-to] [--workspace] [--budget] [--duties]
* [--model-id <id> --provider <p>]
* penguin org leave <agent_id>
* penguin org desk show|renew [<agent_id>]
* penguin org calendar ls [--agent-id] | add <name> … | update <name> … | rm <name>
* penguin org ticket ls [--status] [--owner] [--blocked] | show <id> | create … | move <id> --to <col>
* | assign <id> --owner <p> | block <id> --reason <s> [--by] | unblock <id>
* | progress <id> -m <text> | start <id> [-m] [--workspace] [--agent-id]
* | attach <id> [--session]
* penguin org channel ls | create <id> [--name] [--purpose] | show <id> | invite <id> <principal>...
* | join <id> | leave <id> | remove <id> <principal> | archive <id> | unarchive <id>
* | tail [--channel <id>] [--date <d>] [-n <count>]
* | send -m <text> [--channel <id>] [--ref-ticket] [--ref-session]
* penguin org handbook list | show [path] | write <path> (-m <text> | --file <f>) | rm <path>
* penguin org finance [--period <yyyy-mm>]
*
* Every subcommand takes `--org-id` (default: ADELIE_ORG_ID, the variable company mode
* adds to the control environment of desk and ticket sessions; there is no default
* organization), `--project-id`, `--json` and `--server`. The same environment
* identifies the caller: `--agent-id` on the calendar commands and the desk positional
* default to ADELIE_AGENT_ID; `ticket start` sends it as the employee the ticket
* session runs as (its own `--agent-id` enlists a colleague on the caller's own ticket,
* and outside a session the server picks the ticket owner); the ticket writes and
* the channel writes carry ADELIE_SESSION_ID in their body so the file records the
* employee rather than the token's user, and `ticket attach` attaches that session by
* default. The reads that depend on who is asking — `channel ls`, `channel show`,
* `channel tail` — and the member DELETE behind `leave` / `remove` carry the same
* session as `?sessionId=`, having no body to put it in: without it the server answers
* an employee as the signed-in person and shows it every channel. `--json` prints the
* response DTO as one line (`ticket ls` its filtered list, `channel tail` the messages
* it shows); write commands otherwise print a one-line confirmation.
* Docs: /docs/cli § "penguin org".
*/
import fs from "node:fs";
import path from "node:path";
import type { Command } from "commander";
import type {
MeResponse,
OrgCalendarItem,
OrgCalendarResponse,
OrgCalendarWriteResponse,
OrgChartResponse,
OrgChannelDetail,
OrgChannelItem,
OrgChannelMessage,
OrgChannelMessagesResponse,
OrgChannelsResponse,
OrgHandbookFileResponse,
OrgHandbookFilesResponse,
OrgDeskResponse,
OrgEmployeeItem,
OrgFinanceResponse,
OrgTicketDetail,
OrgTicketItem,
OrgTicketPriority,
OrgTicketStartResponse,
OrgTicketStatus,
OrgTicketsResponse,
OrganizationDetail,
OrganizationsResponse,
} from "@adelie/server/api";
import {
resolveAgentId,
resolveConnection,
resolveProjectId,
resolveSessionRef,
ServerClient,
} from "../client.js";
import { getSessionInfo } from "../server-session.js";
import { dim } from "../render.js";
import { renderTable } from "../table.js";
import type { Messages } from "../i18n.js";
const enc = encodeURIComponent;
/** The kanban columns in board order (the server's ORG_TICKET_COLUMNS; only its types are imported here). */
const TICKET_COLUMNS: readonly OrgTicketStatus[] = [
"proposed",
"in_progress",
"review",
"done",
"rejected",
];
const PRIORITIES: readonly OrgTicketPriority[] = ["P0", "P1", "P2"];
/** `channel tail` without `-n`. */
const DEFAULT_MESSAGE_COUNT = 20;
/** The all-hands channel: what `--channel` means when it is not given (the server's own default). */
const DEFAULT_CHANNEL_ID = "default_channel";
/**
* `create --ceo-budget` when it is not given (the server's own default), in USD per month.
* Budgets accumulate along the reporting line, so the CEO's is the whole company's.
*/
const DEFAULT_CEO_BUDGET = 100;
// ---------------------------------------------------------------------------
// Scope: the organization, its Project and the connection
// ---------------------------------------------------------------------------
interface OrgScope {
client: ServerClient;
projectId: string;
orgId: string;
/** `/api/projects/:p/organizations/:orgId`. */
base: string;
}
/** Prints a localized error line and marks the exit code; the caller returns. */
function fail(t: Messages, message: string): void {
process.stderr.write(`${t.error(message)}\n`);
process.exitCode = 1;
}
/**
* Refuses a caller-supplied id or handbook path holding a `.` / `..` segment: those survive
* encodeURIComponent, and the URL parser then collapses them onto a different route —
* `employees/..` addresses the organization itself rather than one employee. True after the
* error, and the caller returns.
*/
function refuseDotSegments(value: string, t: Messages): boolean {
if (!value.split("/").some((segment) => segment === "." || segment === "..")) return false;
fail(t, t.org.pathSegmentInvalid(value));
return true;
}
/**
* Resolves the organization's coordinates and connects. `--org-id` defaults to
* ADELIE_ORG_ID and to nothing else; it is read before the connection so a missing one
* never auto-starts a server. Null after the error.
*/
async function orgScope(
opts: { orgId?: string; projectId?: string; server?: string },
t: Messages,
): Promise<OrgScope | null> {
const orgId = opts.orgId?.trim() || process.env.ADELIE_ORG_ID?.trim() || "";
if (orgId === "") {
fail(t, t.org.orgIdMissing());
return null;
}
const client = new ServerClient(await resolveConnection({ server: opts.server }, t), t);
const projectId = resolveProjectId(opts.projectId);
return {
client,
projectId,
orgId,
base: `/api/projects/${enc(projectId)}/organizations/${enc(orgId)}`,
};
}
/** The options every organization-scoped leaf command takes, appended after its own. */
function scoped(cmd: Command, t: Messages): Command {
return cmd
.option("--org-id <id>", t.org.orgId)
.option("--project-id <id>", t.common.projectId)
.option("--json", t.common.json)
.option("--server <url>", t.common.server);
}
/** The calling session (the control environment's ADELIE_SESSION_ID), when the CLI runs inside one. */
function callerSessionId(): string | undefined {
return process.env.ADELIE_SESSION_ID?.trim() || undefined;
}
/**
* Who the server records a write as: the calling session and the calling employee, both from
* the control environment, so the file names the employee rather than the token's user. The
* Agent id is the narrower fact — it names exactly the Agent whose subprocess ran the command —
* and the server prefers it; the session answers when there is no Agent id (a signed-in CLI
* outside a session sends neither and the write is the person's).
*/
function actorFields(): { sessionId?: string; agentId?: string } {
const sessionId = callerSessionId();
const agentId = process.env.ADELIE_AGENT_ID?.trim() || undefined;
return {
...(sessionId !== undefined ? { sessionId } : {}),
...(agentId !== undefined ? { agentId } : {}),
};
}
/**
* A `?`-prefixed query string over the entries that have a value; empty when none has.
* `sessionId` and `agentId` ride here on the channel reads and the member DELETE, which have
* no body to carry the identity {@link actorFields} puts in one — without them the server
* answers an employee as the signed-in person, and `channel ls` shows it every channel.
*/
function query(entries: Array<[string, string | undefined]>): string {
const parts = entries
.filter((entry): entry is [string, string] => entry[1] !== undefined)
.map(([key, value]) => `${key}=${enc(value)}`);
return parts.length > 0 ? `?${parts.join("&")}` : "";
}
/** The identity {@link actorFields} carries in a body, as query entries for the reads that have none. */
function actorQuery(): Array<[string, string | undefined]> {
const fields = actorFields();
return [
["sessionId", fields.sessionId],
["agentId", fields.agentId],
];
}
/** `--channel`, trimmed; the all-hands channel when the flag is absent or empty. */
function channelOf(raw: unknown): string {
return (typeof raw === "string" ? raw.trim() : "") || DEFAULT_CHANNEL_ID;
}
/**
* The caller as a channel principal, which `join` and `leave` have to name themselves:
* inside a desk or ticket session it is that session's employee — the identity the server
* derives from the `sessionId` {@link actorFields} sends — and outside one the signed-in
* person, whom only the server knows.
*/
async function callerPrincipal(client: ServerClient): Promise<string> {
const sessionId = callerSessionId();
if (sessionId !== undefined) {
return `agent:${(await getSessionInfo(client, sessionId)).agentId}`;
}
const me = await client.request<MeResponse>("GET", "/api/me");
return `user:${me.user.userId}`;
}
function printJson(value: unknown): void {
process.stdout.write(`${JSON.stringify(value)}\n`);
}
function printLine(text: string): void {
process.stdout.write(`${text}\n`);
}
// ---------------------------------------------------------------------------
// Value parsing and formatting
// ---------------------------------------------------------------------------
/** `--start-at` value: the literal `now` becomes the current instant; anything else passes through for the server to validate. */
function resolveStartAt(raw: string): string {
return raw.trim().toLowerCase() === "now" ? new Date().toISOString() : raw;
}
/** A comma-separated flag value as a trimmed list; undefined when absent or empty. */
function commaList(raw: unknown): string[] | undefined {
if (typeof raw !== "string") return undefined;
const items = raw
.split(",")
.map((s) => s.trim())
.filter((s) => s.length > 0);
return items.length > 0 ? items : undefined;
}
/** A budget flag (`--budget`, `--ceo-budget`): a non-negative number. Null after the error, which names the flag. */
function parseBudget(flag: string, raw: string, t: Messages): number | null {
const value = Number(raw);
if (raw.trim() === "" || !Number.isFinite(value) || value < 0) {
fail(t, t.org.budgetInvalid(flag, raw));
return null;
}
return value;
}
/** A kanban column name (`--status`, `--to`). Null after the error. */
function parseColumn(raw: string, t: Messages): OrgTicketStatus | null {
if ((TICKET_COLUMNS as readonly string[]).includes(raw)) return raw as OrgTicketStatus;
fail(t, t.org.statusInvalid(raw));
return null;
}
/** `--priority`: P0 / P1 / P2. Null after the error. */
function parsePriority(raw: string, t: Messages): OrgTicketPriority | null {
if ((PRIORITIES as readonly string[]).includes(raw)) return raw as OrgTicketPriority;
fail(t, t.org.priorityInvalid(raw));
return null;
}
/** `-n <count>`: a positive integer. Null after the error. */
function parseCount(raw: string, t: Messages): number | null {
const value = Number(raw);
if (!Number.isInteger(value) || value <= 0) {
fail(t, t.org.countInvalid(raw));
return null;
}
return value;
}
/** Costs print with four decimals (cents matter at these magnitudes), budgets with two. */
const usd = (cost: number): string => `$${cost.toFixed(4)}`;
const usdBudget = (budget: number): string => `$${budget.toFixed(2)}`;
/** `$cost / $budget (ratio%)`, or the bare cost without a budget. */
function spendText(spend: { cost: number; budget?: number; ratio?: number }): string {
if (spend.budget === undefined) return usd(spend.cost);
return `${usd(spend.cost)} / ${usdBudget(spend.budget)}${ratioText(spend.ratio)}`;
}
/** Budget cell: `$budget (ratio%)`, or `-` when unbounded. */
function budgetText(budget: number | undefined, ratio: number | undefined): string {
return budget === undefined ? "-" : `${usdBudget(budget)}${ratioText(ratio)}`;
}
function ratioText(ratio: number | undefined): string {
return ratio === undefined ? "" : ` (${Math.round(ratio * 100)}%)`;
}
function isBlocked(item: { blocked?: string }): boolean {
return item.blocked !== undefined && item.blocked !== "";
}
/**
* Depth-first order over a reports-to tree: the roots (no manager) first, each followed by
* its subordinates one level deeper, siblings in their listed order. An employee whose
* manager is not listed (or sits in a cycle) is appended at the root level so nothing goes
* unlisted.
*/
function treeOrder<T extends { agentId: string; reportsTo: string | null }>(
items: readonly T[],
): Array<{ item: T; depth: number }> {
const out: Array<{ item: T; depth: number }> = [];
const seen = new Set<string>();
const walk = (parent: string | null, depth: number): void => {
for (const item of items) {
if (item.reportsTo !== parent || seen.has(item.agentId)) continue;
seen.add(item.agentId);
out.push({ item, depth });
walk(item.agentId, depth + 1);
}
};
walk(null, 0);
for (const item of items) {
if (seen.has(item.agentId)) continue;
seen.add(item.agentId);
out.push({ item, depth: 0 });
}
return out;
}
const indent = (depth: number, text: string): string => `${" ".repeat(depth)}${text}`;
// ---------------------------------------------------------------------------
// Human views
// ---------------------------------------------------------------------------
/** `show`: one line per fact — identity, mission, people, board, money, what waits for the caller. */
function renderDetail(d: OrganizationDetail, t: Messages): string {
const board = TICKET_COLUMNS.map((column) => `${column} ${d.board[column]}`).join(", ");
const lines = [
t.org.showHead(d.name, d.orgId, d.status),
t.org.showMission(d.mission),
t.org.showLanguage(d.settings.language ?? "en"),
t.org.showEmployees(d.employeeCount, d.runningCount, d.pausedCount),
t.org.showBoard(board, d.blockedTickets),
t.org.showSpend(d.spend.period, spendText(d.spend)),
t.org.showPending(
d.pending.mentions,
d.pending.reviewTickets.length,
d.pending.blockedByMe.length,
),
...(d.invalid !== undefined ? [t.org.invalid(d.invalid)] : []),
];
return `${lines.join("\n")}\n`;
}
/** `chart`: the tree as a table whose first column is indented by depth. */
function renderChart(res: OrgChartResponse, t: Messages): string {
return renderTable(
[
t.agent.colId(),
t.agent.colName(),
t.org.colJobTitle(),
t.org.colState(),
t.org.colOwn(),
t.org.colCumulative(),
t.org.colBudget(),
t.org.colNote(),
],
treeOrder(res.employees).map(({ item: e, depth }) => [
indent(depth, e.agentId),
e.name,
e.title,
e.state,
usd(e.spend.own),
usd(e.spend.cumulative),
budgetText(e.budget, e.spend.ratio),
e.invalid !== undefined ? t.org.invalid(e.invalid) : "",
]),
);
}
/** `ticket show`: the derived figures, the ticket's fields, its prose sections, then its history. */
function renderTicket(d: OrgTicketDetail, t: Messages): string {
const label = t.org.ticketFields();
const field = (key: string, value: string): string => `${key}: ${value}`;
const head = [
t.org.ticketHead(d.ticketId, d.status, d.running, isBlocked(d) ? d.blocked : undefined),
t.org.ticketFigures(usd(d.cost), usd(d.rolledUpCost), d.sessions.length, d.children.length),
...(d.invalid !== undefined ? [t.org.invalid(d.invalid)] : []),
field(label.title, d.title),
field(label.owner, d.owner),
...(d.parent !== undefined ? [field(label.parent, d.parent)] : []),
field(label.notify, d.notify.join(", ")),
field(label.priority, d.priority),
...(d.due !== undefined ? [field(label.due, d.due)] : []),
...(isBlocked(d) ? [field(label.blocked, d.blocked ?? "")] : []),
...(d.blockedBy !== undefined && d.blockedBy !== ""
? [field(label.blockedBy, d.blockedBy)]
: []),
field(label.sessions, d.sessions.join(", ")),
];
// The section headings are the file's own: what `show` prints and what an employee edits
// with its file tools have to read as the same document.
const prose = [
`## Goal\n${d.goal}`,
`## Acceptance criteria\n${d.acceptanceCriteria}`,
`## Progress\n${d.progress.map((line) => `- ${line}`).join("\n")}`,
`## Result\n${d.result}`,
].map((section) => section.trimEnd());
// The actions stay in English: they are field values, like the column and the priority.
const history = d.history.map(
(h) => `${h.at} ${h.by} ${h.action}${h.note !== undefined ? `: ${h.note}` : ""}`,
);
const blocks = [
head.join("\n"),
...prose,
...(history.length > 0 ? [`${t.org.ticketHistory()}\n${history.join("\n")}`] : []),
];
return `${blocks.join("\n\n")}\n`;
}
/** `finance`: employees along the reporting line, then tickets, then the total. */
function renderFinance(res: OrgFinanceResponse, t: Messages): string {
const employees = renderTable(
[
t.agent.colId(),
t.org.colJobTitle(),
t.org.colOwn(),
t.org.colCumulative(),
t.org.colBudget(),
t.schedule.colStatus(),
],
treeOrder(res.employees).map(({ item: e, depth }) => [
indent(depth, e.agentId),
e.title,
usd(e.own),
usd(e.cumulative),
budgetText(e.budget, e.ratio),
e.paused ? "paused" : e.warned ? "warned" : "",
]),
);
const tickets =
res.tickets.length === 0
? ""
: `\n${renderTable(
[
t.org.colTicket(),
t.schedule.colStatus(),
t.cost.colCost(),
t.org.colRolledUp(),
t.org.colTitle(),
],
res.tickets.map((x) => [x.ticketId, x.status, usd(x.cost), usd(x.rolledUp), x.title]),
)}`;
return `${employees}${tickets}\n${t.org.financeTotal(res.period, usd(res.total))}\n`;
}
/**
* One channel message per line: `time sender text` (a multi-line text keeps its lines).
* A `system` line the server wrote with a structured notice is rendered in the reader's
* language from that notice; a kind this build does not know falls back to the English text.
*/
function messageLine(m: OrgChannelMessage, t: Messages): string {
return `${m.time} ${m.sender} ${noticeText(m, t)}`;
}
/** The notice's sentence in the reader's language, or the message's own text. */
function noticeText(m: OrgChannelMessage, t: Messages): string {
const notice = m.notice;
if (notice === undefined) return m.text;
// Not every kind is one this build knows: a line a newer server wrote keeps its English.
const render = t.org.notices[notice.kind] as ((p: Record<string, string>) => string) | undefined;
return render === undefined ? m.text : render(notice.params);
}
/** A channel's display name: the all-hands channel is labelled here, its stored name never shown. */
function channelLabel(item: { everyone: boolean; name: string }, t: Messages): string {
return item.everyone ? t.org.allHands() : item.name;
}
/** `channel ls`: one row per channel, the caller's unread counts in the last two columns. */
function renderChannels(items: readonly OrgChannelItem[], t: Messages): string {
return renderTable(
[
t.agent.colId(),
t.agent.colName(),
t.org.colMembers(),
t.org.colArchived(),
t.org.colUnread(),
t.org.colMentions(),
],
items.map((c) => [
c.channelId,
channelLabel(c, t),
String(c.memberCount),
c.archived ? "archived" : "",
String(c.unread),
String(c.mentionsMe),
]),
);
}
/** `channel show`: the facts the channel carries, then its members. */
function renderChannelDetail(d: OrgChannelDetail, t: Messages): string {
const lines = [
t.org.channelHead(channelLabel(d, t), d.channelId, d.memberCount, d.archived),
...(d.purpose !== "" ? [t.org.channelPurposeLine(d.purpose)] : []),
t.org.channelCreatedBy(d.createdBy, d.createdAt),
...(d.lastMessageAt !== null ? [t.org.channelLastMessage(d.lastMessageAt)] : []),
];
const members = renderTable(
[t.org.colPrincipal(), t.agent.colName()],
d.members.map((m) => [m.principal, m.name]),
);
return `${lines.join("\n")}\n\n${members}`;
}
// ---------------------------------------------------------------------------
// Registration
// ---------------------------------------------------------------------------
export function registerOrgCommand(program: Command, t: Messages): void {
const org = program.command("org").description(t.org.desc);
org
.command("ls")
.description(t.org.lsDesc)
.option("--project-id <id>", t.common.projectId)
.option("--json", t.common.json)
.option("--server <url>", t.common.server)
.action(async (opts) => {
const client = new ServerClient(await resolveConnection({ server: opts.server }, t), t);
const projectId = resolveProjectId(opts.projectId);
const res = await client.request<OrganizationsResponse>(
"GET",
`/api/projects/${enc(projectId)}/organizations`,
);
if (opts.json === true) {
printJson(res);
return;
}
if (res.organizations.length === 0) {
printLine(t.org.empty(projectId));
return;
}
process.stdout.write(
renderTable(
[
t.agent.colId(),
t.agent.colName(),
t.schedule.colStatus(),
t.org.colEmployees(),
t.org.colRunning(),
t.org.colOpen(),
t.org.colBlocked(),
t.org.colSpend(),
t.org.colNote(),
],
res.organizations.map((o) => [
o.orgId,
o.name,
o.status,
String(o.employeeCount),
String(o.runningCount),
String(o.openTickets),
String(o.blockedTickets),
spendText(o.spend),
o.invalid !== undefined ? t.org.invalid(o.invalid) : "",
]),
),
);
});
org
.command("create")
.description(t.org.createDesc)
.requiredOption("--org-id <id>", t.org.newOrgId)
.requiredOption("--mission <text>", t.org.mission)
.option("--name <name>", t.org.orgName)
.option("--language <zh|en>", t.org.orgLanguageOption)
.option("--workspace <path>", t.common.workspace)
.option("--ceo-budget <usd>", t.org.ceoBudget, String(DEFAULT_CEO_BUDGET))
.option("--model-id <id>", t.common.modelId)
.option("--provider <name>", t.common.provider)
.option("--project-id <id>", t.common.projectId)
.option("--json", t.common.json)
.option("--server <url>", t.common.server)
.action(async (opts) => {
// A model reference is always the complete (provider, modelId) pair, like everywhere else.
if ((opts.modelId !== undefined) !== (opts.provider !== undefined)) {
fail(t, t.modelRefIncomplete());
return;
}
const ceoBudget = parseBudget("--ceo-budget", String(opts.ceoBudget), t);
if (ceoBudget === null) return;
if (opts.language !== undefined && opts.language !== "zh" && opts.language !== "en") {
fail(t, t.org.languageInvalid(String(opts.language)));
return;
}
const client = new ServerClient(await resolveConnection({ server: opts.server }, t), t);
const projectId = resolveProjectId(opts.projectId);
const detail = await client.request<OrganizationDetail>(
"POST",
`/api/projects/${enc(projectId)}/organizations`,
{
orgId: String(opts.orgId),
mission: String(opts.mission),
...(opts.name !== undefined ? { name: String(opts.name) } : {}),
...(opts.language !== undefined ? { language: opts.language as "zh" | "en" } : {}),
...(opts.workspace !== undefined ? { workspace: String(opts.workspace) } : {}),
ceoBudget,
...(opts.modelId !== undefined
? { model: { provider: String(opts.provider), modelId: String(opts.modelId) } }
: {}),
},
);
if (opts.json === true) printJson(detail);
else printLine(t.org.created(detail.orgId, detail.ceoDeskSessionId));
});
scoped(org.command("show").description(t.org.showDesc), t).action(async (opts) => {
const scope = await orgScope(opts, t);
if (scope === null) return;
const detail = await scope.client.request<OrganizationDetail>("GET", scope.base);
if (opts.json === true) printJson(detail);
else process.stdout.write(renderDetail(detail, t));
});
scoped(org.command("chart").description(t.org.chartDesc), t).action(async (opts) => {
const scope = await orgScope(opts, t);
if (scope === null) return;
const res = await scope.client.request<OrgChartResponse>("GET", `${scope.base}/chart`);
if (opts.json === true) printJson(res);
else process.stdout.write(renderChart(res, t));
});
// ---- employees ----
scoped(
org
.command("hire")
.description(t.org.hireDesc)
.option("--agent-id <id>", t.org.hireAgentId)
.option("--new-agent <id>", t.org.newAgent)
.option("--name <name>", t.org.newAgentName)
.option("--description <text>", t.org.newAgentDescription)
.option("--skills <names>", t.org.skills)
.requiredOption("--title <title>", t.org.title)
.requiredOption("--reports-to <agent_id>", t.org.reportsTo)
.option("--workspace <path>", t.org.hireWorkspace)
.option("--budget <usd>", t.org.budget)
.option("--duties <text>", t.org.duties),
t,
).action(async (opts) => {
// The employee is an existing Agent XOR a new one; the new-Agent fields describe the latter.
if ((opts.agentId !== undefined) === (opts.newAgent !== undefined)) {
fail(t, t.org.hireTargetConflict());
return;
}
if (
opts.newAgent === undefined &&
(opts.name !== undefined || opts.description !== undefined || opts.skills !== undefined)
) {
fail(t, t.org.newAgentFieldsOnly());
return;
}
const budget =
opts.budget !== undefined ? parseBudget("--budget", String(opts.budget), t) : undefined;
if (budget === null) return;
const scope = await orgScope(opts, t);
if (scope === null) return;
const plugins = commaList(opts.skills);
const item = await scope.client.request<OrgEmployeeItem>("POST", `${scope.base}/employees`, {
...(opts.agentId !== undefined ? { agentId: String(opts.agentId) } : {}),
...(opts.newAgent !== undefined
? {
newAgent: {
agentId: String(opts.newAgent),
...(opts.name !== undefined ? { name: String(opts.name) } : {}),
...(opts.description !== undefined ? { description: String(opts.description) } : {}),
...(plugins !== undefined ? { plugins } : {}),
},
}
: {}),
title: String(opts.title),
reportsTo: String(opts.reportsTo),
...(opts.workspace !== undefined ? { workspace: String(opts.workspace) } : {}),
...(budget !== undefined ? { budget } : {}),
...(opts.duties !== undefined ? { duties: String(opts.duties) } : {}),
});
if (opts.json === true) printJson(item);
else printLine(t.org.hired(item.agentId, item.title, item.reportsTo));
});
const employee = org.command("employee").description(t.org.employeeDesc);
scoped(
employee
.command("set <agent_id>")
.description(t.org.employeeSetDesc)
.option("--title <title>", t.org.title)
.option("--reports-to <agent_id>", t.org.reportsTo)
.option("--workspace <path>", t.org.employeeWorkspace)
.option("--budget <usd>", t.org.budget)
.option("--duties <text>", t.org.duties)
.option("--model-id <id>", t.common.modelId)
.option("--provider <group>", t.common.provider),
t,
).action(async (agentId: string, opts) => {
if (refuseDotSegments(agentId, t)) return;
if (Boolean(opts.modelId) !== Boolean(opts.provider)) {
fail(t, t.modelRefIncomplete());
return;
}
const budget =
opts.budget !== undefined ? parseBudget("--budget", String(opts.budget), t) : undefined;
if (budget === null) return;
const body = {
...(opts.title !== undefined ? { title: String(opts.title) } : {}),
...(opts.reportsTo !== undefined ? { reportsTo: String(opts.reportsTo) } : {}),
...(opts.workspace !== undefined ? { workspace: String(opts.workspace) } : {}),
...(budget !== undefined ? { budget } : {}),
...(opts.duties !== undefined ? { duties: String(opts.duties) } : {}),
...(opts.modelId !== undefined
? { model: { provider: String(opts.provider), modelId: String(opts.modelId) } }
: {}),
};
if (Object.keys(body).length === 0) {
fail(t, t.org.nothingToSet());
return;
}
const scope = await orgScope(opts, t);
if (scope === null) return;
const item = await scope.client.request<OrgEmployeeItem>(
"PATCH",
`${scope.base}/employees/${enc(agentId)}`,
body,
);
if (opts.json === true) printJson(item);
else printLine(t.org.employeeUpdated(item.agentId));
});
scoped(org.command("leave <agent_id>").description(t.org.leaveDesc), t).action(
async (agentId: string, opts) => {
if (refuseDotSegments(agentId, t)) return;
const scope = await orgScope(opts, t);
if (scope === null) return;
await scope.client.request("DELETE", `${scope.base}/employees/${enc(agentId)}`);
if (opts.json === true) printJson({ agentId });
else printLine(t.org.left(agentId));
},
);
// ---- desks ----
const desk = org.command("desk").description(t.org.deskDesc);
scoped(desk.command("show [agent_id]").description(t.org.deskShowDesc), t).action(
async (agentArg: string | undefined, opts) => {
const scope = await orgScope(opts, t);
if (scope === null) return;
const agentId = resolveAgentId(agentArg);
const res = await scope.client.request<OrgDeskResponse>(
"GET",
`${scope.base}/employees/${enc(agentId)}/desk`,
);
if (opts.json === true) printJson(res);
else {
printLine(t.org.desk(res.agentId, res.sessionId, res.workspace, res.openedAt, res.created));
}
},
);
scoped(desk.command("renew [agent_id]").description(t.org.deskRenewDesc), t).action(
async (agentArg: string | undefined, opts) => {
const scope = await orgScope(opts, t);
if (scope === null) return;
const agentId = resolveAgentId(agentArg);
const res = await scope.client.request<OrgDeskResponse>(
"POST",
`${scope.base}/employees/${enc(agentId)}/desk`,
);
if (opts.json === true) printJson(res);
else printLine(t.org.deskRenewed(res.agentId, res.sessionId));
},
);
// ---- calendar ----
const calendar = org.command("calendar").description(t.org.calendarDesc);
scoped(
calendar
.command("ls")
.description(t.org.calendarLsDesc)
.option("--agent-id <id>", t.org.calendarAgentId),
t,
).action(async (opts) => {
const scope = await orgScope(opts, t);
if (scope === null) return;
const all = await scope.client.request<OrgCalendarResponse>("GET", `${scope.base}/calendar`);
// Without --agent-id the whole organization's calendar; with it, that employee's events.
const only = opts.agentId !== undefined ? resolveAgentId(opts.agentId) : undefined;
const res: OrgCalendarResponse =
only === undefined
? all
: {
events: all.events.filter((e) => e.agentId === only),
invalidFiles: all.invalidFiles.filter((f) => f.agentId === only),
};
if (opts.json === true) {
printJson(res);
return;
}
const rows: string[][] = res.events.map((e) => [
e.agentId,
e.name,
e.enabled ? t.schedule.enabled() : t.schedule.disabled(),
e.startAt,
e.period ?? t.schedule.oneShot(),
e.nextFireAt ?? "-",
e.lastFiredAt ?? "-",
// Active is the quiet norm; a paused organization or employee skips due slots.
e.status !== "active" ? e.status : e.paused ? "paused" : "",
]);
for (const f of res.invalidFiles) {
rows.push([f.agentId, f.name, "-", "-", "-", "-", "-", "invalid"]);
}
if (rows.length === 0) {
printLine(t.org.calendarEmpty());
return;
}
process.stdout.write(
renderTable(
[
t.agent.colId(),
t.schedule.colName(),
t.schedule.colEnabled(),
t.schedule.colStartAt(),
t.schedule.colPeriod(),
t.org.colNext(),
t.schedule.colLastFired(),
t.schedule.colStatus(),
],
rows,
),
);
});
scoped(
calendar
.command("add <name>")
.description(t.org.calendarAddDesc)
.option("--agent-id <id>", t.org.calendarAgentId)
.requiredOption("--prompt <text>", t.schedule.prompt)
.requiredOption("--start-at <when>", t.schedule.startAt)
.option("--period <duration>", t.schedule.period)
.option("--end-at <iso>", t.schedule.endAt)
.option("--title <title>", t.org.calendarTitle)
.option("--disabled", t.schedule.disabledOpt),
t,
).action(async (name: string, opts) => {
const scope = await orgScope(opts, t);
if (scope === null) return;
const agentId = resolveAgentId(opts.agentId);
const item = await scope.client.request<OrgCalendarWriteResponse>(
"POST",
`${scope.base}/calendar`,
{
agentId,
name,
...(opts.title !== undefined ? { title: String(opts.title) } : {}),
prompt: String(opts.prompt),
// As `schedule add`: an event added through the CLI is meant to fire; --disabled opts out.
enabled: opts.disabled !== true,
startAt: resolveStartAt(String(opts.startAt)),
...(opts.period !== undefined ? { period: String(opts.period) } : {}),
...(opts.endAt !== undefined ? { endAt: String(opts.endAt) } : {}),
},
);
if (opts.json === true) printJson(item);
else printCalendarWrite(t, item);
});
scoped(
calendar
.command("update <name>")
.description(t.org.calendarUpdateDesc)
.option("--agent-id <id>", t.org.calendarAgentId)
.option("--prompt <text>", t.schedule.prompt)
.option("--start-at <when>", t.schedule.startAt)
.option("--period <duration>", t.schedule.period)
.option("--end-at <iso>", t.schedule.endAt)
.option("--title <title>", t.org.calendarTitle)
.option("--enable", t.schedule.enableOpt)
.option("--disable", t.schedule.disableOpt),
t,
).action(async (name: string, opts) => {
if (opts.enable === true && opts.disable === true) {
fail(t, t.schedule.enableDisableConflict());
return;
}
const scope = await orgScope(opts, t);
if (scope === null) return;
const agentId = resolveAgentId(opts.agentId);
const target = `${scope.base}/calendar/${enc(agentId)}/${enc(name)}`;
// Read-modify-write: unspecified fields keep the stored values.
const stored = await scope.client.request<OrgCalendarItem>("GET", target);
const body: Record<string, unknown> = {
enabled: opts.enable === true ? true : opts.disable === true ? false : stored.enabled,
prompt: opts.prompt !== undefined ? String(opts.prompt) : stored.prompt,
startAt: opts.startAt !== undefined ? resolveStartAt(String(opts.startAt)) : stored.startAt,
};
const title = opts.title !== undefined ? String(opts.title) : stored.title;
if (title !== undefined) body.title = title;
const period = opts.period !== undefined ? String(opts.period) : stored.period;
if (period !== undefined) body.period = period;
const endAt = opts.endAt !== undefined ? String(opts.endAt) : stored.endAt;
if (endAt !== undefined) body.endAt = endAt;
const item = await scope.client.request<OrgCalendarWriteResponse>("PUT", target, body);
if (opts.json === true) printJson(item);
else printCalendarWrite(t, item);
});
scoped(
calendar
.command("rm <name>")
.description(t.org.calendarRmDesc)
.option("--agent-id <id>", t.org.calendarAgentId),
t,
).action(async (name: string, opts) => {
const scope = await orgScope(opts, t);
if (scope === null) return;
const agentId = resolveAgentId(opts.agentId);
await scope.client.request("DELETE", `${scope.base}/calendar/${enc(agentId)}/${enc(name)}`);
if (opts.json === true) printJson({ agentId, name });
else printLine(t.org.calendarRemoved(agentId, name));
});
// ---- tickets ----
const ticket = org.command("ticket").description(t.org.ticketDesc);
scoped(
ticket
.command("ls")
.description(t.org.ticketLsDesc)
.option("--status <column>", t.org.statusFilter)
.option("--owner <principal>", t.org.ownerFilter)
.option("--blocked", t.org.blockedFilter),
t,
).action(async (opts) => {
const status = opts.status !== undefined ? parseColumn(String(opts.status), t) : undefined;
if (status === null) return;
const scope = await orgScope(opts, t);
if (scope === null) return;
const res = await scope.client.request<OrgTicketsResponse>("GET", `${scope.base}/tickets`);
// The board comes whole; the filters are local, over every column in board order.
const tickets: OrgTicketItem[] = TICKET_COLUMNS.flatMap((column) => res.columns[column]).filter(
(item) =>
(status === undefined || item.status === status) &&
(opts.owner === undefined || item.owner === String(opts.owner)) &&
(opts.blocked !== true || isBlocked(item)),
);
if (opts.json === true) {
printJson({ tickets, invalidFiles: res.invalidFiles });
return;
}
const rows: string[][] = tickets.map((item) => [
item.ticketId,
item.status,
item.priority,
item.owner ?? "-",
isBlocked(item) ? "blocked" : "",
String(item.sessions.length),
item.title,
]);
for (const f of res.invalidFiles) rows.push([f.path, "invalid", "-", "-", "", "-", f.error]);
if (rows.length === 0) {
printLine(t.org.ticketsEmpty());
return;
}
process.stdout.write(
renderTable(
[
t.agent.colId(),
t.schedule.colStatus(),
t.org.colPriority(),
t.org.colOwner(),
t.org.colBlocked(),
t.agent.colSessions(),
t.org.colTitle(),
],
rows,
),
);
});
scoped(ticket.command("show <ticket_id>").description(t.org.ticketShowDesc), t).action(
async (ticketId: string, opts) => {
const scope = await orgScope(opts, t);
if (scope === null) return;
const detail = await scope.client.request<OrgTicketDetail>(
"GET",
`${scope.base}/tickets/${enc(ticketId)}`,
);
if (opts.json === true) printJson(detail);
else process.stdout.write(renderTicket(detail, t));
},
);
scoped(
ticket
.command("create")
.description(t.org.ticketCreateDesc)
.requiredOption("--title <title>", t.org.ticketTitle)
.option("--slug <slug>", t.org.ticketSlug)
.option("--goal <text>", t.org.goal)
.option("--criteria <text>", t.org.criteria)
.option("--body-file <path>", t.org.bodyFile)
.option("--owner <principal>", t.org.owner)
.option("--parent <ticket_id>", t.org.parent)
.option("--notify <principals>", t.org.notify)
.option("--priority <level>", t.org.priority)
.option("--due <date>", t.org.due),
t,
).action(async (opts) => {
// The content is --goal (with --criteria) XOR the whole Markdown body from a file.
if ((opts.goal !== undefined) === (opts.bodyFile !== undefined)) {
fail(t, t.org.ticketBodyConflict());
return;
}
if (opts.criteria !== undefined && opts.goal === undefined) {
fail(t, t.org.criteriaNeedsGoal());
return;
}
const priority =
opts.priority !== undefined ? parsePriority(String(opts.priority), t) : undefined;
if (priority === null) return;
let body: string | undefined;
if (opts.bodyFile !== undefined) {
try {
body = fs.readFileSync(path.resolve(String(opts.bodyFile)), "utf8");
} catch {
fail(t, t.org.bodyFileUnreadable(String(opts.bodyFile)));
return;
}
}
const scope = await orgScope(opts, t);
if (scope === null) return;
const notify = commaList(opts.notify);
const detail = await scope.client.request<OrgTicketDetail>("POST", `${scope.base}/tickets`, {
title: String(opts.title),
...(opts.slug !== undefined ? { slug: String(opts.slug) } : {}),
...(opts.goal !== undefined ? { goal: String(opts.goal) } : {}),
...(opts.criteria !== undefined ? { acceptanceCriteria: String(opts.criteria) } : {}),
...(body !== undefined ? { body } : {}),
...(opts.owner !== undefined ? { owner: String(opts.owner) } : {}),
...(opts.parent !== undefined ? { parent: String(opts.parent) } : {}),
...(notify !== undefined ? { notify } : {}),
...(priority !== undefined ? { priority } : {}),
...(opts.due !== undefined ? { due: String(opts.due) } : {}),
...actorFields(),
});
if (opts.json === true) printJson(detail);
else printLine(t.org.ticketCreated(detail.ticketId, detail.status));
});
scoped(
ticket
.command("move <ticket_id>")
.description(t.org.ticketMoveDesc)
.requiredOption("--to <column>", t.org.moveTo)
.option("--reason <text>", t.org.moveReason),
t,
).action(async (ticketId: string, opts) => {
const status = parseColumn(String(opts.to), t);
if (status === null) return;
const scope = await orgScope(opts, t);
if (scope === null) return;
const detail = await scope.client.request<OrgTicketDetail>(
"POST",
`${scope.base}/tickets/${enc(ticketId)}/move`,
{
status,
...(opts.reason !== undefined ? { reason: String(opts.reason) } : {}),
...actorFields(),
},
);
if (opts.json === true) printJson(detail);
else printLine(t.org.ticketMoved(detail.ticketId, detail.status));
});
scoped(
ticket
.command("assign <ticket_id>")
.description(t.org.ticketAssignDesc)
.requiredOption("--owner <principal>", t.org.owner),
t,
).action(async (ticketId: string, opts) => {
const scope = await orgScope(opts, t);
if (scope === null) return;
const detail = await scope.client.request<OrgTicketDetail>(
"PUT",
`${scope.base}/tickets/${enc(ticketId)}`,
{ owner: String(opts.owner), ...actorFields() },
);
if (opts.json === true) printJson(detail);
else printLine(t.org.ticketAssigned(detail.ticketId, detail.owner ?? String(opts.owner)));
});
scoped(
ticket
.command("block <ticket_id>")
.description(t.org.ticketBlockDesc)
.requiredOption("--reason <text>", t.org.blockReason)
.option("--by <principal|ticket_id>", t.org.blockedBy),
t,
).action(async (ticketId: string, opts) => {
const scope = await orgScope(opts, t);
if (scope === null) return;
const detail = await scope.client.request<OrgTicketDetail>(
"POST",
`${scope.base}/tickets/${enc(ticketId)}/block`,
{
reason: String(opts.reason),
...(opts.by !== undefined ? { by: String(opts.by) } : {}),
...actorFields(),
},
);
if (opts.json === true) printJson(detail);
else printLine(t.org.ticketBlocked(detail.ticketId));
});
scoped(ticket.command("unblock <ticket_id>").description(t.org.ticketUnblockDesc), t).action(
async (ticketId: string, opts) => {
const scope = await orgScope(opts, t);
if (scope === null) return;
const detail = await scope.client.request<OrgTicketDetail>(
"POST",
`${scope.base}/tickets/${enc(ticketId)}/unblock`,
{ ...actorFields() },
);
if (opts.json === true) printJson(detail);
else printLine(t.org.ticketUnblocked(detail.ticketId));
},
);
scoped(
ticket
.command("progress <ticket_id>")
.description(t.org.ticketProgressDesc)
.requiredOption("-m, --message <text>", t.org.progressText),
t,
).action(async (ticketId: string, opts) => {
const scope = await orgScope(opts, t);
if (scope === null) return;
const detail = await scope.client.request<OrgTicketDetail>(
"POST",
`${scope.base}/tickets/${enc(ticketId)}/progress`,
{ text: String(opts.message), ...actorFields() },
);
if (opts.json === true) printJson(detail);
else printLine(t.org.progressRecorded(detail.ticketId));
});
scoped(
ticket
.command("start <ticket_id>")
.description(t.org.ticketStartDesc)
.option("-m, --message <text>", t.org.startMessage)
.option("--workspace <path>", t.org.startWorkspace)
.option("--agent-id <id>", t.org.startAgentId),
t,
).action(async (ticketId: string, opts) => {
const scope = await orgScope(opts, t);
if (scope === null) return;
// Inside a session the ticket session runs as the calling employee unless --agent-id
// enlists a colleague on the caller's own ticket; outside one the server picks the
// ticket's owner — so the plain default_agent fallback is not applied. `actorFields`
// carries the calling session so the server can tell an employee from a person: an
// employee may start a session only on a ticket it owns, and anyone else's is a 403.
const agentId =
(typeof opts.agentId === "string" ? opts.agentId.trim() : "") ||
process.env.ADELIE_AGENT_ID?.trim() ||
undefined;
const res = await scope.client.request<OrgTicketStartResponse>(
"POST",
`${scope.base}/tickets/${enc(ticketId)}/start`,
{
// `agentId` last: here it is the employee the ticket session RUNS AS, which the
// owner may point at a colleague, and it must not be overwritten by the caller's own.
...actorFields(),
...(agentId !== undefined ? { agentId } : {}),
...(opts.message !== undefined ? { message: String(opts.message) } : {}),
...(opts.workspace !== undefined ? { workspace: String(opts.workspace) } : {}),
},
);
// Like `run --background`: the bare session id is what `penguin input` / `penguin logs` address later.
if (opts.json === true) printJson({ sessionId: res.sessionId });
else printLine(res.sessionId);
});
scoped(
ticket
.command("attach <ticket_id>")
.description(t.org.ticketAttachDesc)
.option("--session <session_id>", t.org.attachSession),
t,
).action(async (ticketId: string, opts) => {
const ref = opts.session !== undefined ? String(opts.session) : callerSessionId();
if (ref === undefined) {
fail(t, t.org.attachSessionMissing());
return;
}
const scope = await orgScope(opts, t);
if (scope === null) return;
const sessionId = await resolveSessionRef(scope.client, scope.projectId, ref, t);
// `sessionId` here is the Session to attach, not the caller's — so only the Agent id of
// {@link actorFields} rides along, and it is what the history entry is recorded under.
const { agentId } = actorFields();
const detail = await scope.client.request<OrgTicketDetail>(
"POST",
`${scope.base}/tickets/${enc(ticketId)}/attach`,
{ sessionId, ...(agentId !== undefined ? { agentId } : {}) },
);
if (opts.json === true) printJson(detail);
else printLine(t.org.ticketAttached(detail.ticketId, sessionId));
});
// ---- channels ----
const channel = org.command("channel").description(t.org.channelDesc);
/** `archive` / `unarchive`: the same PATCH with the flag flipped. */
const setArchived = async (
channelId: string,
archived: boolean,
opts: { orgId?: string; projectId?: string; server?: string; json?: boolean },
): Promise<void> => {
if (refuseDotSegments(channelId, t)) return;
const scope = await orgScope(opts, t);
if (scope === null) return;
const item = await scope.client.request<OrgChannelItem>(
"PATCH",
`${scope.base}/channels/${enc(channelId)}`,
{ archived, ...actorFields() },
);
if (opts.json === true) printJson(item);
else {
printLine(
archived ? t.org.channelArchived(item.channelId) : t.org.channelUnarchived(item.channelId),
);
}
};
scoped(channel.command("ls").description(t.org.channelLsDesc), t).action(async (opts) => {
const scope = await orgScope(opts, t);
if (scope === null) return;
const res = await scope.client.request<OrgChannelsResponse>(
"GET",
`${scope.base}/channels${query(actorQuery())}`,
);
if (opts.json === true) {
printJson(res);
return;
}
if (res.channels.length === 0) {
printLine(t.org.channelsEmpty());
return;
}
process.stdout.write(renderChannels(res.channels, t));
});
scoped(
channel
.command("create <channel_id>")
.description(t.org.channelCreateDesc)
.option("--name <name>", t.org.channelName)
.option("--purpose <text>", t.org.channelPurpose),
t,
).action(async (channelId: string, opts) => {
const scope = await orgScope(opts, t);
if (scope === null) return;
// The id travels in the body, so the server owns every rule about it; a bad one is its
// bad_request, not a second opinion here.
const item = await scope.client.request<OrgChannelItem>("POST", `${scope.base}/channels`, {
channelId,
...(opts.name !== undefined ? { name: String(opts.name) } : {}),
...(opts.purpose !== undefined ? { purpose: String(opts.purpose) } : {}),
...actorFields(),
});
if (opts.json === true) printJson(item);
else printLine(t.org.channelCreated(item.channelId));
});
scoped(channel.command("show <channel_id>").description(t.org.channelShowDesc), t).action(
async (channelId: string, opts) => {
if (refuseDotSegments(channelId, t)) return;
const scope = await orgScope(opts, t);
if (scope === null) return;
const detail = await scope.client.request<OrgChannelDetail>(
"GET",
`${scope.base}/channels/${enc(channelId)}${query(actorQuery())}`,
);
if (opts.json === true) printJson(detail);
else process.stdout.write(renderChannelDetail(detail, t));
},
);
scoped(
channel.command("invite <channel_id> <principals...>").description(t.org.channelInviteDesc),
t,
).action(async (channelId: string, principals: string[], opts) => {
if (refuseDotSegments(channelId, t)) return;
const scope = await orgScope(opts, t);
if (scope === null) return;
// One POST per principal, in order, each printed as it lands: the route takes one
// principal, and a refusal then stops on the one it refused with the rest unsent.
for (const principal of principals) {
const detail = await scope.client.request<OrgChannelDetail>(
"POST",
`${scope.base}/channels/${enc(channelId)}/members`,
{ principal, ...actorFields() },
);
if (opts.json === true) printJson(detail);
else printLine(t.org.channelInvited(detail.channelId, principal));
}
});
scoped(channel.command("join <channel_id>").description(t.org.channelJoinDesc), t).action(
async (channelId: string, opts) => {
if (refuseDotSegments(channelId, t)) return;
const scope = await orgScope(opts, t);
if (scope === null) return;
// The principal is the caller's own, so joining is never an invitation of someone
// else: a person adds itself, and an employee asks for itself and is refused — an
// employee reaches a channel only when a member invites it.
const principal = await callerPrincipal(scope.client);
const detail = await scope.client.request<OrgChannelDetail>(
"POST",
`${scope.base}/channels/${enc(channelId)}/members`,
{ principal, ...actorFields() },
);
if (opts.json === true) printJson(detail);
else printLine(t.org.channelJoined(detail.channelId));
},
);
scoped(channel.command("leave <channel_id>").description(t.org.channelLeaveDesc), t).action(
async (channelId: string, opts) => {
if (refuseDotSegments(channelId, t)) return;
const scope = await orgScope(opts, t);
if (scope === null) return;
const principal = await callerPrincipal(scope.client);
await scope.client.request(
"DELETE",
`${scope.base}/channels/${enc(channelId)}/members/${enc(principal)}${query(actorQuery())}`,
);
if (opts.json === true) printJson({ channelId, principal });
else printLine(t.org.channelLeft(channelId));
},
);
scoped(
channel.command("remove <channel_id> <principal>").description(t.org.channelRemoveDesc),
t,
).action(async (channelId: string, principal: string, opts) => {
if (refuseDotSegments(channelId, t) || refuseDotSegments(principal, t)) return;
const scope = await orgScope(opts, t);
if (scope === null) return;
await scope.client.request(
"DELETE",
`${scope.base}/channels/${enc(channelId)}/members/${enc(principal)}${query(actorQuery())}`,
);
if (opts.json === true) printJson({ channelId, principal });
else printLine(t.org.channelMemberRemoved(channelId, principal));
});
scoped(channel.command("archive <channel_id>").description(t.org.channelArchiveDesc), t).action(
async (channelId: string, opts) => setArchived(channelId, true, opts),
);
scoped(
channel.command("unarchive <channel_id>").description(t.org.channelUnarchiveDesc),
t,
).action(async (channelId: string, opts) => setArchived(channelId, false, opts));
scoped(
channel
.command("tail")
.description(t.org.channelTailDesc)
.option("--channel <id>", t.org.channelOpt)
.option("--date <date>", t.org.channelDate)
.option("-n, --count <count>", t.org.channelCount),
t,
).action(async (opts) => {
const count =
opts.count !== undefined ? parseCount(String(opts.count), t) : DEFAULT_MESSAGE_COUNT;
if (count === null) return;
const channelId = channelOf(opts.channel);
if (refuseDotSegments(channelId, t)) return;
const scope = await orgScope(opts, t);
if (scope === null) return;
const res = await scope.client.request<OrgChannelMessagesResponse>(
"GET",
`${scope.base}/channels/${enc(channelId)}/messages${query([
["date", opts.date !== undefined ? String(opts.date) : undefined],
...actorQuery(),
])}`,
);
const messages = res.messages.slice(-count);
if (opts.json === true) {
printJson({ ...res, messages });
return;
}
if (messages.length === 0) {
printLine(t.org.channelEmpty(res.channelId, res.date));
return;
}
// Message lines carry the sender, never the channel; name it above them whenever the
// reader did not get the default one.
if (res.channelId !== DEFAULT_CHANNEL_ID) printLine(dim(t.org.channelHeader(res.channelId)));
process.stdout.write(`${messages.map((m) => messageLine(m, t)).join("\n")}\n`);
});
scoped(
channel
.command("send")
.description(t.org.channelSendDesc)
.requiredOption("-m, --message <text>", t.org.channelText)
.option("--channel <id>", t.org.channelOpt)
.option("--ref-ticket <ticket_id>", t.org.refTicket)
.option("--ref-session <session_id>", t.org.refSession),
t,
).action(async (opts) => {
const channelId = channelOf(opts.channel);
if (refuseDotSegments(channelId, t)) return;
const scope = await orgScope(opts, t);
if (scope === null) return;
const refs = {
...(opts.refTicket !== undefined ? { ticket: String(opts.refTicket) } : {}),
...(opts.refSession !== undefined ? { session: String(opts.refSession) } : {}),
};
const msg = await scope.client.request<OrgChannelMessage>(
"POST",
`${scope.base}/channels/${enc(channelId)}/messages`,
{
text: String(opts.message),
...(Object.keys(refs).length > 0 ? { refs } : {}),
...actorFields(),
},
);
if (opts.json === true) printJson(msg);
else printLine(t.org.messageSent(msg.id));
});
// ---- handbook ----
const handbook = org.command("handbook").description(t.org.handbookDesc);
/** A handbook path keeps its `/` separators; each segment is encoded on its own. */
const encPath = (rel: string): string => rel.split("/").map(enc).join("/");
scoped(handbook.command("list").description(t.org.handbookListDesc), t).action(async (opts) => {
const scope = await orgScope(opts, t);
if (scope === null) return;
const res = await scope.client.request<OrgHandbookFilesResponse>(
"GET",
`${scope.base}/handbook/files`,
);
if (opts.json === true) {
printJson(res);
return;
}
process.stdout.write(
`${res.files.map((f) => `${f.path}\t${f.size}\t${f.updatedAt}`).join("\n")}\n`,
);
});
scoped(
handbook
.command("show")
.description(t.org.handbookShowDesc)
.argument("[path]", t.org.handbookPath),
t,
).action(async (relArg: string | undefined, opts) => {
const rel = relArg ?? "README.md";
if (refuseDotSegments(rel, t)) return;
const scope = await orgScope(opts, t);
if (scope === null) return;
const res = await scope.client.request<OrgHandbookFileResponse>(
"GET",
`${scope.base}/handbook/files/${encPath(rel)}`,
);
if (opts.json === true) printJson(res);
else process.stdout.write(res.content.endsWith("\n") ? res.content : `${res.content}\n`);
});
scoped(
handbook
.command("write")
.description(t.org.handbookWriteDesc)
.argument("<path>", t.org.handbookPath)
.option("-m, --message <text>", t.org.handbookText)
.option("--file <file>", t.org.handbookFile),
t,
).action(async (rel: string, opts) => {
if (refuseDotSegments(rel, t)) return;
if ((opts.message === undefined) === (opts.file === undefined)) {
fail(t, t.org.handbookOneSource);
return;
}
const content =
opts.file !== undefined ? fs.readFileSync(String(opts.file), "utf8") : String(opts.message);
const scope = await orgScope(opts, t);
if (scope === null) return;
const res = await scope.client.request<OrgHandbookFileResponse>(
"PUT",
`${scope.base}/handbook/files/${encPath(rel)}`,
{ content },
);
if (opts.json === true) printJson(res);
else printLine(t.org.handbookWritten(res.path));
});
scoped(
handbook.command("rm").description(t.org.handbookRmDesc).argument("<path>", t.org.handbookPath),
t,
).action(async (rel: string, opts) => {
if (refuseDotSegments(rel, t)) return;
const scope = await orgScope(opts, t);
if (scope === null) return;
await scope.client.request("DELETE", `${scope.base}/handbook/files/${encPath(rel)}`);
if (opts.json === true) printJson({ ok: true, path: rel });
else printLine(t.org.handbookRemoved(rel));
});
// ---- finance ----
scoped(
org
.command("finance")
.description(t.org.financeDesc)
.option("--period <yyyy-mm>", t.org.period),
t,
).action(async (opts) => {
const scope = await orgScope(opts, t);
if (scope === null) return;
const qs = opts.period !== undefined ? `?period=${enc(String(opts.period))}` : "";
const res = await scope.client.request<OrgFinanceResponse>("GET", `${scope.base}/finance${qs}`);
if (opts.json === true) {
printJson(res);
return;
}
process.stdout.write(renderFinance(res, t));
// Tokens were counted but some model had no pricing: the figures are a lower bound.
if (res.unpriced) process.stderr.write(`${t.org.unpriced()}\n`);
});
}
/**
* A written calendar event: the confirmation line, then the rota advice the server answered
* with — one line each, so a desk that now shares a minute with another is visible at the
* moment the event is written rather than at the month's bill. The warnings stay in the
* server's English; only the label is localized.
*/
function printCalendarWrite(t: Messages, item: OrgCalendarWriteResponse): void {
printLine(
t.org.calendarWritten(
item.agentId,
item.name,
item.enabled ? t.schedule.enabled() : t.schedule.disabled(),
item.nextFireAt,
),
);
for (const warning of item.warnings ?? []) printLine(t.org.calendarWarning(warning));
}