@indigoai-us/hq-cli 5.345.103 → 5.345.105

package/dist/lib/packages/setup-prompt.js

@@ -0,0 +1,128 @@
+/**
+ * The auto-generated "Pack setup" section of a pack bot's system prompt
+ * (build contract section 3). Rendered from the pack's validated `setup:`
+ * block: the questions in order with their options, the one-at-a-time rule
+ * with the `hq-block` suggestions envelope (contract section 2), the exact
+ * command to run with the collected answers, and the done message.
+ */
+import * as path from "node:path";
+export const SKIP_SUGGESTION = "Skip";
+export const HQ_BLOCK_FENCE = "hq-block";
+/** The fenced JSON envelope the app draws as buttons (contract section 2). */
+export function suggestionsEnvelope(items) {
+    const json = JSON.stringify({ v: 1, blocks: [{ kind: "suggestions", items }] });
+    return `\`\`\`${HQ_BLOCK_FENCE}\n${json}\n\`\`\``;
+}
+/** The buttons for one question: its options, plus Skip when it is skippable. */
+export function questionSuggestions(q) {
+    const items = [...q.options];
+    if (q.skippable && !items.includes(SKIP_SUGGESTION))
+        items.push(SKIP_SUGGESTION);
+    return items;
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** `bash <packRoot>/<script> --firm <company slug> --flag '<answer>' ...` */
+export function renderRunCommand(input) {
+    const { setup, packRoot } = input;
+    const flags = setup.questions
+        .filter((q) => setup.run.args[q.id] !== undefined)
+        .map((q) => `${setup.run.args[q.id]} ${shellQuote(`<${q.id}>`)}`);
+    return ["bash", path.join(packRoot, setup.run.script), "--firm", "<company slug>", ...flags].join(" ");
+}
+/** The `then` commands, each run from the pack root with the same --firm. */
+export function renderThenCommands(input) {
+    return input.setup.run.then.map((entry) => {
+        const [first, ...rest] = entry.trim().split(/\s+/);
+        return ["bash", path.join(input.packRoot, first), "--firm", "<company slug>", ...rest].join(" ");
+    });
+}
+/** How to run a pack tool script: node for .mjs/.js, bash otherwise. */
+function toolCommand(packRoot, tool, args) {
+    const runner = /\.(m?js|cjs)$/.test(tool) ? "node" : "bash";
+    return `${runner} ${path.join(packRoot, tool)} ${args}`.trim();
+}
+/** One tool option, rendered with exactly how it connects and how it is read. */
+function renderSourceOption(packRoot, o) {
+    if (o.available === false)
+        return `  - ${o.name}: no direct connection yet${o.note ? ` (${o.note})` : ""}. Offer a workaround if one helps; otherwise say so once, plainly, and move on.`;
+    if (o.tool) {
+        return (`  - ${o.name}: connect with \`${toolCommand(packRoot, o.tool, o.connect ?? "connect")}\`, check with \`${toolCommand(packRoot, o.tool, o.status ?? "status")}\`` +
+            (o.usage ? `, read with \`${toolCommand(packRoot, o.tool, o.usage)}\`` : "") +
+            ` (read-only).`);
+    }
+    return (`  - ${o.name}: connect with \`hq integrations connect ${o.domain} --company <company slug> --link-only\`, read with \`hq integrations tools\` / \`hq integrations call\` (read-only tools only)` +
+        (o.note ? `; ${o.note}` : "") +
+        `.`);
+}
+/**
+ * "Their tools": what the bot needs to know to learn from the person's tools
+ * before asking. Facts (how each tool connects and is read) and principles;
+ * the bot decides how to run the conversation.
+ */
+export function renderLearnFirst(setup, packRoot) {
+    const sources = setup.sources ?? [];
+    const lines = [
+        `### Their tools`,
+        ``,
+        `Start here, before asking about the topics below: most of them should come from their tools, not from questions. \`hq integrations list --usable --json --company <company slug>\` shows what this company already has connected. ` +
+            `Find out which tools they use in whatever way fits the conversation, connect the ones that help, and read them (with a yes first) to fill in as much of the setup as you can; then ask only what is still missing. ` +
+            `Talk about tools by what they are for until the person has named one.`,
+    ];
+    if (sources.length) {
+        lines.push(``, `What each kind of tool is good for, and the routes known to work for common tools. These are examples, not a limit: any tool they use is worth trying. Never tell the person a tool cannot be connected before you have tried the routes below:`, ...sources.flatMap((s) => [`- ${s.kind} (to read ${s.read}; helps with ${s.informs.join(", ")}):`, ...s.options.map((o) => renderSourceOption(path.resolve(packRoot), o))]), ``, `Any other tool: work out how to connect it yourself, trying these in order and stopping at the first that works. ` +
+            `(1) HQ's catalog: \`hq integrations catalog <name> --company <company slug>\`, then \`hq integrations connect <domain> --company <company slug> --link-only\` for a sign-in link. ` +
+            `(2) An access key: if the sign-in needs a key, or the tool only offers API keys or tokens, look up where the tool issues one, tell them the exact steps, and send \`hq secrets --company <company slug> generate-link <TOOL>_API_KEY --expires 1h\` so they paste it into HQ, never into the chat. Then connect with \`hq secrets --company <company slug> get --reveal <TOOL>_API_KEY | hq integrations connect <domain> --company <company slug> --token-stdin\`, or call the tool's own read API with the key through \`hq secrets exec --company <company slug> --only <TOOL>_API_KEY -- <command>\`, never printing it. ` +
+            `(3) A docs page or MCP server: \`hq integrations discover <docs url>\`, or \`hq integrations connect --mcp-url <url> --company <company slug> --link-only\`. ` +
+            `(4) A workaround: an export (CSV, PDF) or a few shared files dropped into the chat, a public page you can read, or the same data in a tool they already connected. ` +
+            `If none works, say so once and move on; the setup does not depend on any one tool.`, ``, `Mechanics: a connect command prints JSON. A \`url\` (or \`authorizationUrl\`) is a link to send them; \`started: true\` means a sign-in page already opened in their browser. ` +
+            `Never run \`hq integrations connect\` without \`--link-only\`: it waits for a sign-in the person has not been sent. ` +
+            `After they say they are done, confirm with the tool's check command (or \`hq integrations list\`).`);
+    }
+    lines.push(``, `Reading: ask before you read, read only what you said you would, and use read-only commands; never send, post or change anything. ` +
+        `Propose what you found with where it came from and let them correct it, rather than asking questions the data already answers. ` +
+        `Describe what you found in your own words; never paste private messages back.`);
+    return lines.join("\n");
+}
+function renderQuestion(q) {
+    const lines = [`- \`${q.id}\`: ${q.goal ?? q.text}`];
+    if (q.goal)
+        lines.push(`  The pack phrases it: "${q.text}"`);
+    if (q.options.length)
+        lines.push(`  Typical answers (to help you understand, not to show as buttons): ${q.options.join(", ")}`);
+    if (q.default_from)
+        lines.push(`  Start from the value of \`${q.default_from}\` and let them confirm or change it.`);
+    lines.push(q.skippable ? `  Optional: if they would rather not say, pass \`skipped\`.` : `  Required.`);
+    return lines.join("\n");
+}
+/** The whole "## Pack setup" section: a brief, not a script. */
+export function renderPackSetupSection(input) {
+    const { setup, packName, packRoot } = input;
+    const parts = [];
+    parts.push(`## Pack setup (${packName})\n\n` +
+        `You are the setup bot of the \`${packName}\` pack, installed at \`${packRoot}\`. Set the pack up for this person from this chat. ` +
+        `This section is a brief, not a script: it says what you need to learn, what you can use, and what done looks like. How you run the conversation is your call. Adapt to the person: follow their lead, skip what you already know, ask follow-ups when an answer is vague, and keep messages short. ` +
+        `You run every command yourself; never ask the person to open a terminal or Claude Code. ` +
+        `Everything you write in a turn is posted to the person, including text between commands, so never narrate your steps or write notes to yourself. ` +
+        `Keep your progress in \`pack-setup-${packName}.md\` in your memory folder so a later turn carries on instead of starting over.`);
+    parts.push(renderLearnFirst(setup, packRoot));
+    parts.push(`### What you need to learn\n\n${setup.questions.map(renderQuestion).join("\n")}`);
+    if (setup.documents?.length) {
+        parts.push(`### Documents\n\nThese are worth asking for if their tools do not have them: ${setup.documents.join(", ")}. They can drop files into the chat; read what arrives and use it.`);
+    }
+    parts.push(`### Buttons\n\n` +
+        `You can offer tap-to-answer buttons by ending a message with an \`${HQ_BLOCK_FENCE}\` fenced JSON envelope, for example ${suggestionsEnvelope(["Done", "Skip"])} The app draws each item as a button and sends its text back as the person's reply. ` +
+        `Use them only when there is a real, short set of choices: at most four, all of the same kind (never mix answers with actions like connecting a tool). Leave them off questions answered by typing, and never put a guessed or example answer in one. Typed replies always work too.`);
+    const thenCommands = renderThenCommands(input);
+    parts.push(`### Setting it up\n\n` +
+        `When you know enough, run this from the HQ folder, filling each \`<question id>\` with what you learned (\`skipped\` when they skipped) and \`<company slug>\` with their company's folder under \`companies/\`:\n\n` +
+        `\`\`\`bash\n${renderRunCommand(input)}\n\`\`\`` +
+        (thenCommands.length ? `\n\nThen, with the same \`--firm\`:\n\n\`\`\`bash\n${thenCommands.join("\n")}\n\`\`\`` : "") +
+        `\n\nIf a command fails, say plainly what did not work and offer to try again; never paste a stack trace.`);
+    parts.push(`### When it is done\n\n` +
+        `Tell them what you set up: what you created and where to find it in Files, what you connected, and anything left undone. The pack's own summary of the moment is: "${setup.done.message}"` +
+        (setup.done.suggestion ? ` A natural next step to offer: "${setup.done.suggestion}".` : ""));
+    return parts.join("\n\n");
+}
+//# sourceMappingURL=setup-prompt.js.map

package/dist/lib/packages/setup-takeover.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Takeover of HQ's generic setup by a pack bot (build contract section 3).
+ *
+ * When a pack's `setup.takeover_setup` is true and HQ's setup bot has not
+ * recorded that setup is finished, the pack bot's system prompt also carries
+ * the setup worker's skills and a note to finish HQ setup first, then run the
+ * pack setup. "Finished" follows the setup worker's own rule: its progress
+ * note (`setup-progress.md` in the setup bot's memory folder) says
+ * `Status: finished`. No note, or any other status, means not finished.
+ *
+ * Where the note lives: the setup bot's config at `~/.hq/bots/setup/bot.json`
+ * names its memory folder (`personal/workers/setup/memory` under the HQ root
+ * for synced memory, or `~/.hq/bots/setup/memory` for local memory).
+ */
+import type { WorkerSkillSource } from "../bot/prompt.js";
+export declare const HQ_SETUP_BOT_NAME = "setup";
+export declare const SETUP_PROGRESS_NOTE = "setup-progress.md";
+/** Same rule as the setup worker: the note says `Status: finished`. */
+export declare function progressNoteSaysFinished(note: string | null | undefined): boolean;
+/**
+ * The HQ setup bot's progress note on this computer, or null when the setup
+ * bot was never created here or has not written one.
+ */
+export declare function readHqSetupProgressNote(opts?: {
+    botsRoot?: string;
+    hqRootFallback?: string;
+}): {
+    path: string | null;
+    note: string | null;
+};
+/**
+ * Whether the pack bot takes over HQ setup: the pack asked for it and the
+ * progress note does not say setup is finished.
+ */
+export declare function decideTakeover(input: {
+    takeoverSetup: boolean;
+    progressNote: string | null | undefined;
+}): boolean;
+export interface TakeoverPromptInput {
+    packName: string;
+    /** hqRoot-relative folder of HQ's setup worker. */
+    setupWorkerDir: string;
+    /** The setup worker's skills (name, description, hqRoot-relative file). */
+    skills: readonly WorkerSkillSource[];
+    /** Where HQ's setup bot keeps (or would keep) its progress note; null when unknown. */
+    progressNotePath: string | null;
+}
+/** The "## Finish HQ setup first" section, placed before the pack setup section. */
+export declare function renderTakeoverSection(input: TakeoverPromptInput): string;
+//# sourceMappingURL=setup-takeover.d.ts.map

package/dist/lib/packages/setup-takeover.js

@@ -0,0 +1,75 @@
+/**
+ * Takeover of HQ's generic setup by a pack bot (build contract section 3).
+ *
+ * When a pack's `setup.takeover_setup` is true and HQ's setup bot has not
+ * recorded that setup is finished, the pack bot's system prompt also carries
+ * the setup worker's skills and a note to finish HQ setup first, then run the
+ * pack setup. "Finished" follows the setup worker's own rule: its progress
+ * note (`setup-progress.md` in the setup bot's memory folder) says
+ * `Status: finished`. No note, or any other status, means not finished.
+ *
+ * Where the note lives: the setup bot's config at `~/.hq/bots/setup/bot.json`
+ * names its memory folder (`personal/workers/setup/memory` under the HQ root
+ * for synced memory, or `~/.hq/bots/setup/memory` for local memory).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readBotConfig, resolveBotMemoryDir } from "../bot/config.js";
+import { botDir } from "../bot/paths.js";
+export const HQ_SETUP_BOT_NAME = "setup";
+export const SETUP_PROGRESS_NOTE = "setup-progress.md";
+/** Same rule as the setup worker: the note says `Status: finished`. */
+export function progressNoteSaysFinished(note) {
+    if (typeof note !== "string")
+        return false;
+    return /^Status:[ \t]*finished/im.test(note);
+}
+/**
+ * The HQ setup bot's progress note on this computer, or null when the setup
+ * bot was never created here or has not written one.
+ */
+export function readHqSetupProgressNote(opts = {}) {
+    const config = readBotConfig(botDir(HQ_SETUP_BOT_NAME, opts.botsRoot));
+    if (!config)
+        return { path: null, note: null };
+    const notePath = path.join(resolveBotMemoryDir(config), SETUP_PROGRESS_NOTE);
+    return { path: notePath, note: readNote(notePath) };
+}
+function readNote(p) {
+    try {
+        return fs.readFileSync(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether the pack bot takes over HQ setup: the pack asked for it and the
+ * progress note does not say setup is finished.
+ */
+export function decideTakeover(input) {
+    if (!input.takeoverSetup)
+        return false;
+    return !progressNoteSaysFinished(input.progressNote);
+}
+/** The "## Finish HQ setup first" section, placed before the pack setup section. */
+export function renderTakeoverSection(input) {
+    const skillLines = input.skills.map((s) => {
+        const desc = s.description ? ` — ${s.description}` : "";
+        const file = s.file ? ` — ${s.file}` : " — (no skill file on disk)";
+        return `- ${s.name}${desc}${file}`;
+    });
+    return (`## Finish HQ setup first\n\n` +
+        `HQ's own setup bot has not recorded that this HQ is set up` +
+        (input.progressNotePath ? ` (its progress note at \`${input.progressNotePath}\` does not say \`Status: finished\`)` : " (it has no progress note on this computer)") +
+        `. Before the \`${input.packName}\` pack setup, finish the generic HQ setup yourself, using HQ's setup worker skills below: ` +
+        `read \`${path.join(input.setupWorkerDir, "worker.yaml")}\` for the walkthrough and its progress-note rules, do only the steps that are not done, and ` +
+        (input.progressNotePath
+            ? `keep HQ's setup progress note at \`${input.progressNotePath}\` up to date as you go (not a copy in your own memory folder), ending with \`Status: finished\`, so HQ's setup bot and later packs see that setup is done. `
+            : `write the same \`setup-progress.md\` note in your memory folder as you go, ending with \`Status: finished\`. `) +
+        `Skip any step the HQ plainly shows is done (signed in, a company they belong to). Then carry on with the Pack setup section. ` +
+        `Tell the person in one line that you are finishing HQ setup first, and ask one question at a time, as the Pack setup section says.\n\n` +
+        `### HQ setup worker skills (${path.join(input.setupWorkerDir, "skills")}/)\n\n` +
+        (skillLines.length ? skillLines.join("\n") : "- (none found on disk)"));
+}
+//# sourceMappingURL=setup-takeover.js.map

package/dist/lib/packages/start-bot.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `hq packages install <source> --start-bot` (sample-pack-in-app-setup US-003,
+ * build contract section 3).
+ *
+ * After a pack with a valid `setup:` block is wired, create the personal bot
+ * `setup.bot.name` running the pack worker of the same id, with the display
+ * name and intro from the block, through the same code path as
+ * `hq bot create` (never a child `hq` process), and start it the way
+ * `hq bot create` does (launchd when installed). A bot of that name that
+ * already exists is restarted and re-sends its intro. If the bot cannot start,
+ * the install still succeeds: the reason is printed and the owner gets one
+ * plain DM with one next step. On success the install prints `bot: <name>`,
+ * which the desktop app reads to open the right DM.
+ */
+import type { PackSetup } from "../../types.js";
+export interface StartPackBotDeps {
+    /** A bot of this name exists on this computer. */
+    botExists: (name: string) => boolean;
+    /** `hq bot create <name> --worker <id> --display-name ... --intro ... --kickoff ...` */
+    createBot: (name: string, opts: {
+        worker: string;
+        displayName: string;
+        intro: string;
+        kickoff: string;
+    }) => Promise<void>;
+    /** `hq bot restart <name>` */
+    restartBot: (name: string) => Promise<void>;
+    /** `hq bot intro <name>` (re-send the hello) */
+    sendIntro: (name: string) => Promise<void>;
+    /** One DM to the owner, best effort; failures are reported, never thrown. */
+    dmOwner: (name: string, body: string) => Promise<void>;
+    /** Human output (stdout). */
+    say: (line: string) => void;
+}
+export interface StartPackBotResult {
+    ok: boolean;
+    bot: string;
+    /** "created" | "restarted" */
+    action: "created" | "restarted";
+    reason?: string;
+}
+/** The kickoff turn that makes the bot begin the pack setup as soon as it is online. */
+export declare function packSetupKickoff(packName: string, setup: PackSetup): string;
+/** One plain sentence plus one next step, for the owner's DM when the start failed. */
+export declare function startFailureDm(setup: PackSetup, reason: string): string;
+export declare function startPackSetupBot(packName: string, setup: PackSetup, deps: StartPackBotDeps): Promise<StartPackBotResult>;
+//# sourceMappingURL=start-bot.d.ts.map

package/dist/lib/packages/start-bot.js

@@ -0,0 +1,66 @@
+/**
+ * `hq packages install <source> --start-bot` (sample-pack-in-app-setup US-003,
+ * build contract section 3).
+ *
+ * After a pack with a valid `setup:` block is wired, create the personal bot
+ * `setup.bot.name` running the pack worker of the same id, with the display
+ * name and intro from the block, through the same code path as
+ * `hq bot create` (never a child `hq` process), and start it the way
+ * `hq bot create` does (launchd when installed). A bot of that name that
+ * already exists is restarted and re-sends its intro. If the bot cannot start,
+ * the install still succeeds: the reason is printed and the owner gets one
+ * plain DM with one next step. On success the install prints `bot: <name>`,
+ * which the desktop app reads to open the right DM.
+ */
+/** The kickoff turn that makes the bot begin the pack setup as soon as it is online. */
+export function packSetupKickoff(packName, setup) {
+    return (`Kickoff: I just added the ${packName} pack and you are its setup bot. Begin now. ` +
+        `Follow the Pack setup section of your instructions: if a "Finish HQ setup first" section is present, start there; ` +
+        `otherwise ask the first setup question (\`${setup.questions[0].id}\`) with its suggestions. One question per message.`);
+}
+/** One plain sentence plus one next step, for the owner's DM when the start failed. */
+export function startFailureDm(setup, reason) {
+    const next = `hq bot start ${setup.bot.name}`;
+    return `${setup.bot.display_name} could not start (${plain(reason)}). Next step: open Terminal and run \`${next}\`, or ask your setup bot to start it.`;
+}
+function plain(reason) {
+    return reason.replace(/\s+/g, " ").trim().replace(/[.:]+$/, "");
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export async function startPackSetupBot(packName, setup, deps) {
+    const name = setup.bot.name;
+    const exists = deps.botExists(name);
+    const action = exists ? "restarted" : "created";
+    try {
+        if (exists) {
+            deps.say(`bot ${name} already exists; restarting it and sending its intro again`);
+            await deps.restartBot(name);
+            await deps.sendIntro(name);
+        }
+        else {
+            await deps.createBot(name, {
+                worker: name,
+                displayName: setup.bot.display_name,
+                intro: setup.bot.intro,
+                kickoff: packSetupKickoff(packName, setup),
+            });
+        }
+        deps.say(`bot: ${name}`);
+        return { ok: true, bot: name, action };
+    }
+    catch (err) {
+        const reason = errorMessage(err);
+        deps.say(`bot ${name} could not be started: ${reason}`);
+        deps.say(`The pack is installed. Start the bot later with: hq bot start ${name}`);
+        try {
+            await deps.dmOwner(name, startFailureDm(setup, reason));
+        }
+        catch (dmErr) {
+            deps.say(`could not DM you about it: ${errorMessage(dmErr)}`);
+        }
+        return { ok: false, bot: name, action, reason };
+    }
+}
+//# sourceMappingURL=start-bot.js.map

package/dist/lib/session-company-lock.d.ts

@@ -0,0 +1,7 @@
+export type SessionCompanyLock = {
+    sessionId: string;
+    companies: string[];
+} | undefined;
+/** Read the session's validated company scope capability or legacy metadata. */
+export declare function readSessionCompanyLock(env?: NodeJS.ProcessEnv): SessionCompanyLock;
+//# sourceMappingURL=session-company-lock.d.ts.map

package/dist/lib/session-company-lock.js

@@ -0,0 +1,97 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { resolveSessionId } from "./core-utils/session-id.js";
+import { resolveDefaultHqRoot } from "../utils/hq-root-resolver.js";
+/** Read the session's validated company scope capability or legacy metadata. */
+export function readSessionCompanyLock(env = process.env) {
+    const root = resolveDefaultHqRoot({ env });
+    const sessionId = resolveSessionId(root, env);
+    if (!sessionId)
+        return undefined;
+    const sessionDir = path.join(root, "workspace/sessions", sessionId);
+    const capabilityPath = path.join(sessionDir, "scope-capability.json");
+    const metaPath = path.join(sessionDir, "meta.yaml");
+    let primary;
+    let companies;
+    let hasCapability = false;
+    try {
+        fs.lstatSync(capabilityPath);
+        hasCapability = true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "ENOENT" && code !== "ENOTDIR")
+            throw new Error("Cannot verify this session's company lock because its scope capability is unreadable.");
+    }
+    if (hasCapability) {
+        let value;
+        try {
+            value = JSON.parse(fs.readFileSync(capabilityPath, "utf8"));
+        }
+        catch {
+            throw new Error("Cannot verify this session's company lock because its scope capability is unreadable.");
+        }
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error("Cannot verify this session's company lock because its scope capability is invalid.");
+        const cap = value;
+        if (cap.session_id !== sessionId)
+            throw new Error("Cannot verify this session's company lock because its scope capability does not match the active session.");
+        if (typeof cap.company_slug !== "string" || !/^[A-Za-z0-9_-]+$/.test(cap.company_slug))
+            throw new Error("Cannot verify this session's company lock because its scope capability is invalid.");
+        primary = cap.company_slug;
+        if (cap.company_slugs === undefined)
+            companies = [primary];
+        else if (Array.isArray(cap.company_slugs)
+            && cap.company_slugs.length > 0
+            && cap.company_slugs.every((slug) => typeof slug === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(slug))
+            && cap.company_slugs[0] === primary
+            && new Set(cap.company_slugs).size === cap.company_slugs.length
+            && ((primary === "personal" && cap.company_slugs.length === 1)
+                || (primary !== "personal" && !cap.company_slugs.includes("personal"))))
+            companies = [...cap.company_slugs];
+        else
+            throw new Error("Cannot verify this session's company lock because its scope capability is invalid.");
+    }
+    else {
+        try {
+            const meta = fs.readFileSync(metaPath, "utf8");
+            const read = (key) => meta.split(/\r?\n/).find((line) => new RegExp(`^\\s*${key}:`).test(line))?.replace(/^\s*[^:]+:\s*/, "").replace(/^"|"$/g, "") ?? "";
+            primary = read("company_slug");
+            const hasList = meta.split(/\r?\n/).some((line) => /^\s*company_slugs:/.test(line));
+            const listed = hasList ? read("company_slugs") : "";
+            if (hasList && (!listed || !primary))
+                throw new Error("invalid company lock");
+            companies = hasList ? listed.split(",") : primary ? [primary] : [];
+            if (companies.some((slug) => !/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(slug)))
+                throw new Error("invalid company lock");
+            if (new Set(companies).size !== companies.length)
+                throw new Error("invalid company lock");
+            if (primary && companies[0] !== primary)
+                throw new Error("invalid company lock");
+            if (companies.length > 1 && companies.includes("personal"))
+                throw new Error("invalid company lock");
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ENOENT" || code === "ENOTDIR" || code === "EACCES")
+                return { sessionId, companies: [] };
+            throw new Error("Cannot verify this session's company lock because its metadata is invalid.");
+        }
+    }
+    const real = companies.filter((slug) => {
+        if (slug === "personal")
+            return true;
+        try {
+            const companyPath = path.join(root, "companies", slug);
+            const stat = fs.lstatSync(companyPath);
+            return stat.isDirectory() && !stat.isSymbolicLink();
+        }
+        catch {
+            return false;
+        }
+    });
+    if (primary && real[0] !== primary)
+        return { sessionId, companies: [] };
+    return { sessionId, companies: real };
+}
+//# sourceMappingURL=session-company-lock.js.map

package/dist/types.d.ts

@@ -127,6 +127,88 @@ export interface PackManifest {
         entrypoint: string;
         prompt?: string;
     };
+    /**
+     * Guided in-app setup. Optional — absent on
+     * legacy packs, which install unchanged. Validated by
+     * `lib/packages/setup-block.ts`; `hq packages install --start-bot` creates the
+     * bot it names and the bot's system prompt renders the questions and the run
+     * command from it.
+     */
+    setup?: PackSetup;
+}
+/** One question the pack bot asks, in order. */
+export interface PackSetupQuestion {
+    id: string;
+    text: string;
+    /** Suggested answers shown as buttons; may be empty (free text only). */
+    options: string[];
+    /** The bot proposes this value and asks to confirm (e.g. company_display_name). */
+    default_from?: string;
+    skippable: boolean;
+    /** What the bot needs to learn from this question; it follows up until it has that. */
+    goal?: string;
+}
+export interface PackSetup {
+    bot: {
+        /** Bot handle; also the worker id under contributes.workers. ^[a-z0-9-]{2,32}$ */
+        name: string;
+        display_name: string;
+        intro: string;
+    };
+    /** When true and HQ's setup bot has not finished, the pack bot finishes HQ setup first. */
+    takeover_setup: boolean;
+    questions: PackSetupQuestion[];
+    run: {
+        /** Relative to the pack root; must exist in the pack. */
+        script: string;
+        /** question id -> flag (the bot passes --firm itself). */
+        args: Record<string, string>;
+        /** Commands run after `script`, in order; each first token exists in the pack. */
+        then: string[];
+    };
+    done: {
+        message: string;
+        suggestion?: string;
+    };
+    /** Documents worth asking for at the start (a rate card, a past proposal); the bot reads them and asks less. */
+    documents?: string[];
+    /**
+     * Kinds of tools the bot asks about, connects and reads (with the owner's
+     * yes) to answer questions itself before asking them: sent client emails for
+     * voice, CRM deals for pricing. `informs` names question ids.
+     */
+    sources?: PackSetupSource[];
+}
+/**
+ * One tool a source can be. It connects in one of two ways: through HQ
+ * integrations (`domain`, a sign-in link from `hq integrations connect`), or
+ * through a script the pack ships (`tool`, run with `connect` / `status` and
+ * read with `usage`). `available: false` means the pack cannot read it yet.
+ */
+export interface PackSetupSourceOption {
+    name: string;
+    domain?: string;
+    /** Pack-relative script (.mjs/.js run with node, .sh with bash). */
+    tool?: string;
+    /** Arguments that start the connection (default "connect"). It prints JSON: a `url` to send, or `started: true` when it opened a sign-in page itself. */
+    connect?: string;
+    /** Arguments that report the connection (default "status"); JSON with `connected`. */
+    status?: string;
+    /** How to read with the tool, e.g. "search <terms> | recent | read <id>". */
+    usage?: string;
+    available?: boolean;
+    /** Shown to the bot when `available` is false, e.g. "coming in a later update". */
+    note?: string;
+}
+export interface PackSetupSource {
+    /** The kind of tool, as the person would say it: "email", "CRM", "team chat", "docs". */
+    kind: string;
+    /** What to read from it, in words the bot repeats when it asks: "the last 30 emails you sent to clients". */
+    read: string;
+    /** Question ids this source can answer. */
+    informs: string[];
+    /** Likely tools for this kind and how each one connects. */
+    options: PackSetupSourceOption[];
 }
 export {};
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.103",
+  "version": "5.345.105",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {