@indigoai-us/hq-cli 5.345.155 → 5.345.159

package/dist/commands/deploy-access.js

@@ -0,0 +1,322 @@
+import { createInterface } from "node:readline/promises";
+import { deployApiRequest } from "../lib/deploy-api.js";
+import { listDeployApps } from "../lib/deploy-apps.js";
+import { DEFAULT_HQ_ROOT, ensureCognitoToken } from "../utils/cognito-session.js";
+import { getCompanyUid, looksLikeCompanyUid } from "../utils/vault-api.js";
+import { displayText, safeJson } from "./deploy-comments.js";
+import { readActiveCompanySlug } from "./skill.js";
+/**
+ * `hq deploy access` reads and changes a deploy app's access policy through
+ * hq-deploy's GET/PUT /api/apps/:id/access-policy (the same API the HQ console
+ * access modal uses). Feedback bcd64202-071a-4d01-9005-3329a13ca4ae.
+ */
+export const DEPLOY_ACCESS_MODES = ["company", "selected", "public"];
+class DeployAccessError extends Error {
+}
+/**
+ * Terminal hooks for the approval prompt. Tests replace these; production reads
+ * the real TTY state and asks on stdin.
+ */
+export const deployAccessPrompt = {
+    isInteractive: () => Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    ask: async (question) => {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        try {
+            return await rl.question(question);
+        }
+        finally {
+            rl.close();
+        }
+    },
+};
+/**
+ * Changes that make an app public or drop its password gate need explicit
+ * approval: --yes, or an interactive "yes". Non-interactive without --yes
+ * fails closed before any write.
+ */
+async function requireApproval(app, current, record, mode, yes) {
+    // DeployAccessMode never includes password, so any change from a password
+    // app removes the password.
+    const removesPassword = current.mode === "password" || record?.passwordProtected === true;
+    const goesPublic = mode === "public" && current.mode !== "public";
+    if (!removesPassword && !goesPublic)
+        return;
+    const name = displayText(app);
+    const from = displayText(current.mode ?? "unknown");
+    const suffix = mode === "public" ? " (anyone with the link can open it)" : "";
+    console.error(`This changes access for '${name}' from ${from} to ${mode}${suffix}.`);
+    if (removesPassword) {
+        console.error(`Warning: this removes the password protection on '${name}'.`);
+    }
+    if (yes)
+        return;
+    if (!deployAccessPrompt.isInteractive()) {
+        throw new DeployAccessError(`Refusing to change access for '${name}' without approval. Re-run with --yes to confirm. Nothing was changed.`);
+    }
+    const answer = (await deployAccessPrompt.ask("Type 'yes' to continue: ")).trim().toLowerCase();
+    if (answer !== "yes" && answer !== "y") {
+        throw new DeployAccessError("Cancelled. Nothing was changed.");
+    }
+}
+const SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
+function resolveCompany(companyFlag) {
+    const slug = companyFlag ?? readActiveCompanySlug(DEFAULT_HQ_ROOT);
+    if (slug === undefined)
+        throw new DeployAccessError("No active company. Pass --company <slug>.");
+    if (!SLUG_PATTERN.test(slug))
+        throw new DeployAccessError("The company slug is not valid.");
+    return slug;
+}
+export function parseMode(raw) {
+    if (DEPLOY_ACCESS_MODES.includes(raw))
+        return raw;
+    throw new DeployAccessError(`Unknown access mode '${displayText(raw)}'. Use one of: ${DEPLOY_ACCESS_MODES.join(", ")}.`);
+}
+function str(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function grantees(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((item) => (item && typeof item === "object" ? str(item.id) : null))
+        .filter((id) => id !== null)
+        .map((id) => ({ id }));
+}
+export function toView(body) {
+    return {
+        appId: str(body.appId),
+        mode: str(body.mode),
+        // Only a saved policy carries a real company uid. hq-deploy returns an
+        // empty companyUid when no policy is saved; orgId is the hq-deploy org id,
+        // which the PUT rejects (ACCESS_POLICY_COMPANY_MISMATCH).
+        companyUid: str(body.companyUid),
+        users: grantees(body.users),
+        groups: grantees(body.groups),
+        policyVersion: typeof body.policyVersion === "number" ? body.policyVersion : null,
+        updatedAt: str(body.updatedAt),
+    };
+}
+function collect(value, previous = []) {
+    const id = value.trim();
+    if (id.length === 0)
+        throw new DeployAccessError("Member ids must not be empty.");
+    return [...previous, id];
+}
+async function errorFor(response, slug, what) {
+    const body = await response.json().catch(() => ({}));
+    const raw = body.error?.code;
+    const code = typeof raw === "string" && /^[A-Z0-9_]+$/.test(raw) ? raw : `HTTP_${response.status}`;
+    if (response.status === 401) {
+        return new DeployAccessError(`hq-deploy rejected your sign-in. Run 'hq login' and retry. (${code})`);
+    }
+    if (response.status === 403) {
+        return new DeployAccessError(`You need to be the app owner or a company admin in '${slug}' to manage access. (${code})`);
+    }
+    if (response.status === 404)
+        return new DeployAccessError(`App not found in '${slug}'. (${code})`);
+    if (response.status === 400) {
+        const message = typeof body.error?.message === "string" ? displayText(body.error.message) : "invalid request";
+        return new DeployAccessError(`hq-deploy refused the change: ${message} (${code})`);
+    }
+    const message = typeof body.error?.message === "string" ? `: ${displayText(body.error.message)}` : "";
+    return new DeployAccessError(`Could not ${what} (HTTP ${response.status}, ${code})${message}.`);
+}
+async function request(token, slug, route, method, body) {
+    try {
+        return await deployApiRequest(token, route, method, body, { "X-Org-Slug": slug });
+    }
+    catch {
+        throw new DeployAccessError("Could not reach hq-deploy.");
+    }
+}
+async function readJson(response) {
+    const body = await response.json().catch(() => null);
+    if (!body || typeof body !== "object")
+        throw new DeployAccessError("hq-deploy returned an invalid response.");
+    return body;
+}
+/** Resolve an app id, subdomain or exact name to its hq-deploy app id. */
+async function resolveApp(token, slug, app) {
+    if (/^app_[A-Za-z0-9_-]+$/.test(app))
+        return { id: app, record: null };
+    const apps = await listDeployApps(async (cursor) => {
+        const route = cursor ? `/api/apps?cursor=${encodeURIComponent(cursor)}` : "/api/apps";
+        const response = await request(token, slug, route, "GET");
+        if (!response.ok)
+            throw await errorFor(response, slug, "list deploy apps");
+        return readJson(response);
+    });
+    const needle = app.toLowerCase();
+    const matches = apps
+        .filter((item) => typeof item === "object" && item !== null)
+        .filter((item) => [item.id, item.subdomain, item.name].some((field) => typeof field === "string" && field.toLowerCase() === needle));
+    const ids = [...new Set(matches.map((item) => str(item.id)).filter((id) => id !== null))];
+    if (ids.length === 0)
+        throw new DeployAccessError(`No deploy app '${displayText(app)}' in '${slug}'.`);
+    if (ids.length > 1) {
+        throw new DeployAccessError(`'${displayText(app)}' matches ${ids.length} apps in '${slug}'. Use the app id.`);
+    }
+    const id = ids[0];
+    return { id, record: matches.find((item) => item.id === id) ?? null };
+}
+async function resolveAppId(token, slug, app) {
+    return (await resolveApp(token, slug, app)).id;
+}
+/**
+ * The hq-pro company uid the PUT must carry. Order: the saved policy, the app
+ * record, then the company slug (--company or the active company) resolved in
+ * the caller's own companies. Never the hq-deploy orgId.
+ */
+async function resolvePolicyCompanyUid(token, slug, policy, record) {
+    const fromPolicy = policy.companyUid;
+    if (fromPolicy && looksLikeCompanyUid(fromPolicy))
+        return fromPolicy;
+    const fromApp = record ? str(record.companyUid) : null;
+    if (fromApp && looksLikeCompanyUid(fromApp))
+        return fromApp;
+    const resolved = await getCompanyUid(token, slug).catch(() => null);
+    if (resolved && looksLikeCompanyUid(resolved))
+        return resolved;
+    throw new DeployAccessError(`Could not find the HQ company id for '${slug}'. Check --company, run 'hq login', and retry.`);
+}
+async function getPolicy(token, slug, appId) {
+    const response = await request(token, slug, `/api/apps/${encodeURIComponent(appId)}/access-policy`, "GET");
+    if (!response.ok)
+        throw await errorFor(response, slug, "read the access policy");
+    return toView(await readJson(response));
+}
+function applyEdits(current, add = [], remove = []) {
+    const removeSet = new Set(remove);
+    const ids = current.map((g) => g.id).filter((id) => !removeSet.has(id));
+    for (const id of add)
+        if (!ids.includes(id) && !removeSet.has(id))
+            ids.push(id);
+    return ids.map((id) => ({ id }));
+}
+function printPolicy(view, app) {
+    console.log(`App: ${displayText(app)}`);
+    console.log(`Mode: ${displayText(view.mode ?? "unknown")}`);
+    if (view.mode === "selected") {
+        console.log(`Users: ${view.users.length ? view.users.map((u) => displayText(u.id)).join(", ") : "(none)"}`);
+        console.log(`Groups: ${view.groups.length ? view.groups.map((g) => displayText(g.id)).join(", ") : "(none)"}`);
+    }
+    if (view.policyVersion !== null)
+        console.log(`Policy version: ${view.policyVersion}`);
+}
+async function getAction(app, options) {
+    const slug = resolveCompany(options.company);
+    const token = await ensureCognitoToken();
+    const appId = await resolveAppId(token, slug, app);
+    const view = await getPolicy(token, slug, appId);
+    if (options.json) {
+        console.log(safeJson({ company: slug, app: appId, policy: view }));
+        return;
+    }
+    printPolicy(view, app);
+}
+async function setAction(app, options) {
+    // Validate locally first: an unknown mode never reaches the network.
+    const requestedMode = options.mode === undefined ? undefined : parseMode(options.mode);
+    const editsMembers = [options.addUser, options.removeUser, options.addGroup, options.removeGroup]
+        .some((list) => list !== undefined && list.length > 0);
+    if (requestedMode === undefined && !editsMembers) {
+        await getAction(app, options);
+        return;
+    }
+    const slug = resolveCompany(options.company);
+    const token = await ensureCognitoToken();
+    const { id: appId, record } = await resolveApp(token, slug, app);
+    const current = await getPolicy(token, slug, appId);
+    const mode = requestedMode ?? current.mode;
+    if (mode !== "selected" && editsMembers) {
+        throw new DeployAccessError("Member lists only apply to selected mode. Add --mode selected, or switch the app to selected first.");
+    }
+    if (mode === null || !DEPLOY_ACCESS_MODES.includes(mode)) {
+        throw new DeployAccessError(`The app is in '${displayText(current.mode ?? "unknown")}' mode. Pass --mode.`);
+    }
+    // hq-deploy stores the member lists for every mode. Keep the saved lists when
+    // switching away from selected so switching back restores them.
+    const users = applyEdits(current.users, options.addUser, options.removeUser);
+    const groups = applyEdits(current.groups, options.addGroup, options.removeGroup);
+    if (mode === "selected" && users.length === 0 && groups.length === 0) {
+        throw new DeployAccessError("Selected mode needs at least one member. Pass --add-user <id> or --add-group <id>.");
+    }
+    // A direct app id skips the list lookup, so read the org-scoped app record
+    // before deciding whether this write drops a password. The access-policy row
+    // can lag the app's own passwordProtected flag, which hq-deploy toggles
+    // separately through PATCH /apps. Fail closed when the state is unknown.
+    let approvalRecord = record;
+    if (approvalRecord === null) {
+        const appResponse = await request(token, slug, `/api/apps/${encodeURIComponent(appId)}`, "GET");
+        if (!appResponse.ok)
+            throw await errorFor(appResponse, slug, "read the deploy app");
+        approvalRecord = await readJson(appResponse);
+        if (approvalRecord.id !== appId || typeof approvalRecord.passwordProtected !== "boolean") {
+            throw new DeployAccessError("Could not verify the app's password protection. Nothing was changed.");
+        }
+    }
+    const companyUid = await resolvePolicyCompanyUid(token, slug, current, approvalRecord);
+    await requireApproval(app, current, approvalRecord, mode, options.yes);
+    const response = await request(token, slug, `/api/apps/${encodeURIComponent(appId)}/access-policy`, "PUT", {
+        mode,
+        companyUid,
+        users,
+        groups,
+    });
+    if (!response.ok)
+        throw await errorFor(response, slug, "update the access policy");
+    const updated = toView(await readJson(response));
+    if (options.json) {
+        console.log(safeJson({ company: slug, app: appId, policy: updated }));
+        return;
+    }
+    printPolicy(updated, app);
+}
+async function run(action) {
+    try {
+        await action();
+    }
+    catch (error) {
+        if (error instanceof DeployAccessError) {
+            console.error(error.message);
+        }
+        else {
+            // Unexpected failure: show the error type and message, never a stack or body.
+            const detail = error instanceof Error ? `${error.name}: ${displayText(error.message)}` : "unknown error";
+            console.error(`Deploy access command failed (${detail}).`);
+        }
+        process.exitCode = 1;
+    }
+}
+export function registerDeployAccessCommand(deploy) {
+    const access = deploy
+        .command("access")
+        .description("Show or change who can open a deploy app (company, selected members, or public)")
+        .argument("[app]", "app id, subdomain, or exact name")
+        .option("--company <slug>", "use this company instead of the active company")
+        .option("--mode <mode>", `access mode: ${DEPLOY_ACCESS_MODES.join(" | ")}`)
+        .option("--add-user <id>", "add a selected member by person id (repeatable)", collect)
+        .option("--remove-user <id>", "remove a selected member by person id (repeatable)", collect)
+        .option("--add-group <id>", "add a selected group by id (repeatable)", collect)
+        .option("--remove-group <id>", "remove a selected group by id (repeatable)", collect)
+        .option("--json", "print the resulting policy as JSON")
+        .option("--yes", "approve making the app public or removing its password without a prompt")
+        .action(async (app, options, command) => {
+        if (!app) {
+            command.help({ error: true });
+            return;
+        }
+        await run(() => setAction(app, options));
+    });
+    access
+        .command("get <app>")
+        .description("Show an app's current access mode and selected members")
+        .option("--company <slug>", "use this company instead of the active company")
+        .option("--json", "print the policy as JSON")
+        .action(async (app, _options, command) => {
+        // --company/--json may be parsed by the parent `access` command.
+        await run(() => getAction(app, command.optsWithGlobals()));
+    });
+}
+//# sourceMappingURL=deploy-access.js.map

package/dist/commands/dm-attach.d.ts

@@ -0,0 +1,106 @@
+/**
+ * `hq dm send --attach <path>` — upload local files as chat attachments and
+ * hand the resulting `attachments[]` to the DM / channel message post.
+ *
+ * Storage contract (hq-pro files-presign + notify-dm, hq-desktop-app
+ * `upload-chat-attachments`): every chat upload lands under
+ * `chat/attachments/{dm|chan}/<scopeId>/<file>` in a VAULT SCOPE that the
+ * presign call names in `company`:
+ *   - a 1:1 DM is stored in the SENDER's personal vault, scope = the caller's
+ *     own `prs_` uid, under `dm/<uidA--uidB>/` (the two participant uids,
+ *     sorted ascending). files-presign authorizes `put` for either member.
+ *   - a company channel is stored in that company's vault, scope = the
+ *     channel's `companyUid`, under `chan/<channelId>/`. A personal channel
+ *     (no companyUid) uses the caller's personal vault, as the desktop app does.
+ * The message row carries only metadata; the server checks on send that each
+ * vaultPath belongs to the conversation and that `companyUid` matches the
+ * channel's company. Readers use `companyUid` as the presign scope on `get`.
+ *
+ * Network is injected (`presign`, `put`) so the sequence is unit-testable.
+ */
+import { type PutResponse } from "./library-add.js";
+export declare const MAX_DM_ATTACHMENTS = 5;
+export declare const MAX_DM_ATTACHMENT_BYTES: number;
+/** Metadata the send body carries for one uploaded file. */
+export interface DmAttachmentWire {
+    vaultPath: string;
+    /** Vault scope the bytes live in (cmp_… or the sender's prs_…). */
+    companyUid: string;
+    name: string;
+    sizeBytes: number;
+    contentType: string;
+}
+/** One validated local file, before upload. */
+export interface LocalAttachment {
+    path: string;
+    name: string;
+    sizeBytes: number;
+    contentType: string;
+}
+export type ChatAttachmentScope = {
+    scope: "dm";
+    uids: [string, string];
+} | {
+    scope: "chan";
+    channelId: string;
+};
+/** Reduce a local file name to one safe path component (mirrors the desktop app). */
+export declare function sanitizeAttachmentName(raw: string): string;
+/** `yyyymmddThhmmss` in UTC — a sortable per-send prefix that keeps same-named files apart. */
+export declare function attachmentTimestamp(now: Date): string;
+/** The server's DM pair key is `[a,b].sort().join("#")` with `#` rendered as `--` in keys. */
+export declare function dmAttachmentScopeId(a: string, b: string): string;
+/** Build the scope-relative vault key for one upload. Pure. */
+export declare function buildChatAttachmentKey(args: {
+    target: ChatAttachmentScope;
+    name: string;
+    now: Date;
+}): string;
+/**
+ * Check every `--attach` path before anything touches the network: it must
+ * exist, be a regular file, and fit the server cap; at most five per message.
+ * Throws an Error that names the offending file.
+ */
+export declare function validateAttachmentPaths(paths: readonly string[], stat?: (p: string) => {
+    isFile(): boolean;
+    size: number;
+}): LocalAttachment[];
+export interface AttachmentUploadDeps {
+    /** POST /v1/files/presign with `{ company, keys }`. */
+    presign: (token: string, body: Record<string, unknown>) => Promise<Response>;
+    /** PUT one file's bytes to a presigned URL with the returned headers. */
+    put: (file: LocalAttachment, url: string, headers: Record<string, string>) => Promise<PutResponse>;
+}
+export declare const defaultAttachmentUploadDeps: AttachmentUploadDeps;
+/**
+ * Presign-put every file into `scopeUid`, then return the `attachments[]`
+ * entries for the send body. One presign request covers all files (hq-pro
+ * rate-limits presign per user). Any refusal aborts before the message is
+ * sent, so a DM never references bytes that are not there.
+ */
+export declare function uploadDmAttachments(args: {
+    token: string;
+    scopeUid: string;
+    target: ChatAttachmentScope;
+    files: LocalAttachment[];
+    now?: Date;
+    deps?: AttachmentUploadDeps;
+}): Promise<DmAttachmentWire[]>;
+/**
+ * The vault scope for a channel post: the channel's company when it has one,
+ * else the caller's own personal vault. Mirrors the desktop app's
+ * `attachmentVaultScopeUid` (no "first company" fallback).
+ */
+export declare function attachmentScopeForChannel(channel: {
+    companyUid?: string;
+    scope?: string;
+}, callerUid: string): string;
+/**
+ * The caller's own vault scope for a 1:1 DM attachment. Only a person
+ * (`prs_`) has a personal vault; files-presign refuses any other scope uid, so
+ * an agent sender (agt_) is refused here before the upload is attempted.
+ */
+export declare function personalScopeForCaller(callerUid: string | undefined): string;
+/** Render the confirmation lines listing where each attachment landed. */
+export declare function formatUploadedAttachments(files: readonly DmAttachmentWire[]): string;
+//# sourceMappingURL=dm-attach.d.ts.map

package/dist/commands/dm-attach.js

@@ -0,0 +1,184 @@
+/**
+ * `hq dm send --attach <path>` — upload local files as chat attachments and
+ * hand the resulting `attachments[]` to the DM / channel message post.
+ *
+ * Storage contract (hq-pro files-presign + notify-dm, hq-desktop-app
+ * `upload-chat-attachments`): every chat upload lands under
+ * `chat/attachments/{dm|chan}/<scopeId>/<file>` in a VAULT SCOPE that the
+ * presign call names in `company`:
+ *   - a 1:1 DM is stored in the SENDER's personal vault, scope = the caller's
+ *     own `prs_` uid, under `dm/<uidA--uidB>/` (the two participant uids,
+ *     sorted ascending). files-presign authorizes `put` for either member.
+ *   - a company channel is stored in that company's vault, scope = the
+ *     channel's `companyUid`, under `chan/<channelId>/`. A personal channel
+ *     (no companyUid) uses the caller's personal vault, as the desktop app does.
+ * The message row carries only metadata; the server checks on send that each
+ * vaultPath belongs to the conversation and that `companyUid` matches the
+ * channel's company. Readers use `companyUid` as the presign scope on `get`.
+ *
+ * Network is injected (`presign`, `put`) so the sequence is unit-testable.
+ */
+import { createReadStream, statSync } from "node:fs";
+import path from "node:path";
+import { vaultApiFetch } from "../utils/vault-api.js";
+import { contentTypeFor, streamPut } from "./library-add.js";
+export const MAX_DM_ATTACHMENTS = 5;
+export const MAX_DM_ATTACHMENT_BYTES = 25 * 1024 * 1024;
+/** Reduce a local file name to one safe path component (mirrors the desktop app). */
+export function sanitizeAttachmentName(raw) {
+    const base = raw.trim().split(/[/\\]/).pop() ?? "file";
+    const cleaned = base.replace(/[^\w.\- ()[\]]+/g, "_").replace(/^\.+/, "");
+    return cleaned.slice(0, 180) || "file";
+}
+/** `yyyymmddThhmmss` in UTC — a sortable per-send prefix that keeps same-named files apart. */
+export function attachmentTimestamp(now) {
+    return now.toISOString().replace(/[-:]/g, "").slice(0, 15);
+}
+/** The server's DM pair key is `[a,b].sort().join("#")` with `#` rendered as `--` in keys. */
+export function dmAttachmentScopeId(a, b) {
+    return [a, b].sort().join("--");
+}
+/** Build the scope-relative vault key for one upload. Pure. */
+export function buildChatAttachmentKey(args) {
+    const scopeId = args.target.scope === "dm"
+        ? dmAttachmentScopeId(args.target.uids[0], args.target.uids[1])
+        : args.target.channelId;
+    if (!scopeId || scopeId.includes("/")) {
+        throw new Error("Cannot build an attachment key: the conversation id is missing or malformed.");
+    }
+    return `chat/attachments/${args.target.scope}/${scopeId}/${attachmentTimestamp(args.now)}-${sanitizeAttachmentName(args.name)}`;
+}
+function formatBytes(n) {
+    if (n >= 1024 * 1024)
+        return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+    if (n >= 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${n} B`;
+}
+/**
+ * Check every `--attach` path before anything touches the network: it must
+ * exist, be a regular file, and fit the server cap; at most five per message.
+ * Throws an Error that names the offending file.
+ */
+export function validateAttachmentPaths(paths, stat = statSync) {
+    if (paths.length > MAX_DM_ATTACHMENTS) {
+        throw new Error(`Too many attachments: ${paths.length} given, at most ${MAX_DM_ATTACHMENTS} per message.`);
+    }
+    const out = [];
+    for (const raw of paths) {
+        const p = raw.trim();
+        if (!p)
+            throw new Error("--attach requires a non-empty file path.");
+        let st;
+        try {
+            st = stat(p);
+        }
+        catch {
+            throw new Error(`Attachment not found: ${p}`);
+        }
+        if (!st.isFile()) {
+            throw new Error(`Attachment is not a regular file: ${p}`);
+        }
+        if (st.size > MAX_DM_ATTACHMENT_BYTES) {
+            throw new Error(`Attachment too large: ${p} is ${formatBytes(st.size)}; the limit is 25 MB.`);
+        }
+        const name = sanitizeAttachmentName(path.basename(p));
+        out.push({ path: p, name, sizeBytes: st.size, contentType: contentTypeFor(name) });
+    }
+    return out;
+}
+export const defaultAttachmentUploadDeps = {
+    presign: (token, body) => vaultApiFetch({ token, path: "/v1/files/presign", method: "POST", body }),
+    put: (file, url, headers) => streamPut(url, headers, createReadStream(file.path), file.sizeBytes),
+};
+/**
+ * Presign-put every file into `scopeUid`, then return the `attachments[]`
+ * entries for the send body. One presign request covers all files (hq-pro
+ * rate-limits presign per user). Any refusal aborts before the message is
+ * sent, so a DM never references bytes that are not there.
+ */
+export async function uploadDmAttachments(args) {
+    const deps = args.deps ?? defaultAttachmentUploadDeps;
+    const now = args.now ?? new Date();
+    if (args.files.length === 0)
+        return [];
+    const planned = args.files.map((file) => ({
+        file,
+        key: buildChatAttachmentKey({ target: args.target, name: file.name, now }),
+    }));
+    const res = await deps.presign(args.token, {
+        company: args.scopeUid,
+        keys: planned.map((p) => ({ key: p.key, op: "put", contentType: p.file.contentType })),
+    });
+    if (!res.ok) {
+        const err = (await res.json().catch(() => ({})));
+        const message = typeof err.error === "string" ? err.error : typeof err.message === "string" ? err.message : res.statusText;
+        throw new Error(`Could not prepare the attachment upload (HTTP ${res.status}): ${message}`);
+    }
+    const data = (await res.json().catch(() => ({})));
+    const rows = new Map();
+    for (const row of data.results ?? []) {
+        if (row && typeof row === "object" && typeof row.key === "string") {
+            rows.set(row.key, row);
+        }
+    }
+    const out = [];
+    for (const p of planned) {
+        const row = rows.get(p.key);
+        if (!row || typeof row.url !== "string") {
+            const reason = typeof row?.error === "string" ? row.error : "the vault refused the upload";
+            throw new Error(`Attachment refused: ${p.file.path} — ${reason}`);
+        }
+        const headers = {};
+        if (row.headers && typeof row.headers === "object") {
+            for (const [k, v] of Object.entries(row.headers)) {
+                if (typeof v === "string")
+                    headers[k] = v;
+            }
+        }
+        const put = await deps.put(p.file, row.url, headers);
+        if (put.status < 200 || put.status >= 300) {
+            throw new Error(`Upload failed for ${p.file.path} (HTTP ${put.status}). The message was not sent.`);
+        }
+        out.push({
+            vaultPath: p.key,
+            companyUid: args.scopeUid,
+            name: p.file.name,
+            sizeBytes: p.file.sizeBytes,
+            contentType: p.file.contentType,
+        });
+    }
+    return out;
+}
+/**
+ * The vault scope for a channel post: the channel's company when it has one,
+ * else the caller's own personal vault. Mirrors the desktop app's
+ * `attachmentVaultScopeUid` (no "first company" fallback).
+ */
+export function attachmentScopeForChannel(channel, callerUid) {
+    const fromChannel = channel.companyUid?.trim() ?? "";
+    if (fromChannel && !fromChannel.startsWith("prs_"))
+        return fromChannel;
+    return callerUid;
+}
+/**
+ * The caller's own vault scope for a 1:1 DM attachment. Only a person
+ * (`prs_`) has a personal vault; files-presign refuses any other scope uid, so
+ * an agent sender (agt_) is refused here before the upload is attempted.
+ */
+export function personalScopeForCaller(callerUid) {
+    if (!callerUid) {
+        throw new Error("Could not read your person uid from the session token — run `hq login` and try again.");
+    }
+    if (!callerUid.startsWith("prs_")) {
+        throw new Error(`--attach on a 1:1 DM needs a personal vault, which only a person sender has (you are ${callerUid}). Post the file to a company channel instead.`);
+    }
+    return callerUid;
+}
+/** Render the confirmation lines listing where each attachment landed. */
+export function formatUploadedAttachments(files) {
+    return files
+        .map((f) => `  [file] ${f.name} (${formatBytes(f.sizeBytes)})\n     vault: ${f.vaultPath}`)
+        .join("\n");
+}
+//# sourceMappingURL=dm-attach.js.map

package/dist/commands/dm.d.ts

@@ -1,4 +1,5 @@
 import { Command } from "commander";
+import { type DmAttachmentWire } from "./dm-attach.js";
 export interface DmRecipient {
     toEmail?: string;
     toPersonUid?: string;
@@ -48,6 +49,8 @@ export interface ChannelSummary {
         personUid: string;
         displayName?: string;
     }[];
+    /** Set on company-scoped channels; the vault scope their attachments live in. */
+    companyUid?: string;
 }
 /**
  * Find the caller's channel(s) whose name matches `name`, by slug or
@@ -57,6 +60,28 @@ export interface ChannelSummary {
  * unit-testable.
  */
 export declare function matchChannelsByName(channels: ChannelSummary[], name: string): ChannelSummary[];
+/** One row from GET /v1/notify/contacts (persons the caller can DM). */
+export interface DmContact {
+    personUid?: string;
+    email?: string;
+    displayName?: string;
+}
+/**
+ * Find the single contact whose display name (case-insensitive, or by slug)
+ * equals a bare recipient name. Email local parts are not matched: they are not
+ * the name the user sees, and matching them would divert channel posts. A bare word like `setup` used
+ * to go straight to a channel lookup, so `hq dm send setup` landed in a channel
+ * whose slug was `setup` even when a person by that name existed (feedback
+ * eba06f59). Returns null when nothing or more than one contact matches. Pure.
+ */
+export declare function matchContactByName(contacts: DmContact[], name: string): DmContact | null;
+/**
+ * The confirmation line for a channel send. When the typed target is not the
+ * channel's own display name (for example `hq dm setup` matching a channel
+ * whose slug is `setup` but whose display name is `welcome`), say what it
+ * resolved to: the typed text, the channel's scope, and its id. Pure.
+ */
+export declare function formatChannelPostedLine(channel: ChannelSummary, typed: string): string;
 /** Server-side cap on one post's mentions (hq-pro MAX_CHANNEL_MENTIONS). */
 export declare const MAX_CHANNEL_MENTIONS = 25;
 /**
@@ -142,6 +167,8 @@ export interface DmSendBody {
     details?: string;
     deliverAt?: string;
     audience?: DmAudience;
+    /** Uploaded chat attachments (`--attach`); the server accepts up to 5. */
+    attachments?: DmAttachmentWire[];
 }
 /**
  * Build the POST /v1/notify/dm request body from CLI inputs. Pure (no I/O,
@@ -159,7 +186,17 @@ export declare function buildDmBody(args: {
     inDelay?: string;
     now: number;
     audience?: string;
+    attachments?: DmAttachmentWire[];
 }): DmSendBody;
+/**
+ * The other participant's uid for a 1:1 DM attachment key. A `prs_`/`agt_`
+ * recipient is already a uid; an email is looked up in the caller's contacts
+ * (GET /v1/notify/contacts), the same route `dm forward --from <email>` uses.
+ * There is no separate "person by email" route on the vault API, and a DM to
+ * someone outside your contacts is a connection request anyway, which the
+ * server holds without delivering files.
+ */
+export declare function resolveDmPeerUid(token: string, recipient: string): Promise<string>;
 /** A pending incoming connection request, as returned by the backend. */
 export interface ConnectionRequest {
     pairKey: string;