@indigoai-us/hq-cli 5.61.0 → 5.62.0

package/dist/commands/skill.js

@@ -0,0 +1,593 @@
+/**
+ * `hq skill` subcommand group (US-017).
+ *
+ * Terminal / scriptable access to the skill collaboration loop:
+ *
+ *   hq skill suggest <uid|path>   Propose a change to a skill from working edits.
+ *   hq skill list-suggestions     Show the review inbox (suggestions on skills you own).
+ *   hq skill review <sgn_…>       Accept (merge) or decline a pending suggestion.
+ *
+ * This is a THIN front-end over the SAME wired hq-pro routes the MCP surface
+ * (US-007) and the console merge path (US-009) use — there is NO forked
+ * suggestion or merge logic here. The CLI reads the local working SKILL.md,
+ * computes the proposed content (+ its base for a diff), and POSTs to:
+ *
+ *   CREATE  POST /v1/files/skills/company/{slug}/{skillUid}/suggestions
+ *   LIST    POST /v1/files/skills/company/{slug}/suggestions/list
+ *   ACCEPT  POST /v1/files/skills/company/{slug}/{skillUid}/suggestions/{id}/accept
+ *   DECLINE POST /v1/files/skills/company/{slug}/{skillUid}/suggestions/{id}/decline
+ *
+ * The skill routes are keyed on the company SLUG (path param, resolved
+ * server-side via findEntityBySlug) — NOT the companyUid the vault/ACL routes
+ * use — so this module resolves a slug (from `--company` or the active company)
+ * and passes it straight through.
+ *
+ * Lock semantics (AC3): a suggest against a skill the caller cannot WRITE still
+ * SUCCEEDS as a proposal. The CREATE route is MEMBER-gated (never write-gated),
+ * so this command performs NO client-side lock/permission pre-check — it always
+ * posts and renders whatever the server returns. A locked-out member lands a
+ * suggestion, never a hard permission error.
+ *
+ * Attribution (AC4): the invoking identity (from the Cognito JWT) is the server-
+ * derived `authorPersonUid`; the CLI never sends an author. An optional
+ * `--note` rides as `authorNote` (the change's rationale / failure context).
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5bdf8a18-3088-5615-b596-9be2c9fdb5cc")}catch(e){}}();
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import chalk from "chalk";
+import yaml from "js-yaml";
+import simpleGit from "simple-git";
+import { ensureCognitoToken, DEFAULT_HQ_ROOT } from "../utils/cognito-session.js";
+import { vaultApiFetch } from "../utils/vault-api.js";
+// ---------------------------------------------------------------------------
+// Patterns
+// ---------------------------------------------------------------------------
+/**
+ * A `skl_…` argument to `suggest` is a skill UID (resolve the local file from
+ * it); anything else is a filesystem path. Lenient on the suffix (the strict
+ * `skl_<ulid>` shape is `isSkillUid` on the server) so a hand-typed / fixture
+ * uid still routes to the uid branch.
+ */
+export const SKILL_UID_PATTERN = /^skl_[A-Za-z0-9]+$/;
+/** A `sgn_…` suggestion id — the `review` target and the LIST row key. */
+export const SUGGESTION_ID_PATTERN = /^sgn_[A-Za-z0-9]+$/;
+const VALID_LIST_STATUSES = ["open", "accepted", "declined", "all"];
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for unit tests)
+// ---------------------------------------------------------------------------
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+/**
+ * Read the top-level `skill_uid` from a SKILL.md's YAML frontmatter. Mirrors
+ * hq-pro's `parseSkillFrontmatter` (block extraction → YAML parse → read the
+ * top-level `skill_uid` string). Returns `undefined` when there is no
+ * frontmatter, it fails to parse, or `skill_uid` is absent / not a `skl_…`
+ * string. Never throws.
+ */
+export function parseSkillUid(md) {
+    const match = md.match(FRONTMATTER_RE);
+    if (!match)
+        return undefined;
+    let doc;
+    try {
+        doc = yaml.load(match[1]);
+    }
+    catch {
+        return undefined;
+    }
+    if (!doc || typeof doc !== "object" || Array.isArray(doc))
+        return undefined;
+    const uid = doc.skill_uid;
+    return typeof uid === "string" && SKILL_UID_PATTERN.test(uid) ? uid : undefined;
+}
+/** sha256 hex of a string — the base-version fingerprint the server records (AC2). */
+export function sha256Hex(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+/**
+ * Build the CREATE request body from the resolved proposed content and an
+ * optional base. Mirrors the server's two payload shapes:
+ *   - `baseContent` present → the server derives the unified diff + base hash
+ *     (the diff-by-default path). A no-op (base === proposed) is rejected here
+ *     rather than round-tripped to an EmptySuggestion 400.
+ *   - no base → a `full-file` proposal; the server REQUIRES a `baseContentHash`,
+ *     so we fingerprint the proposed content (a "here is my whole file" proposal
+ *     with no base to diff against).
+ * An empty / whitespace-only note is dropped (kept absent, not blank).
+ */
+export function buildSuggestionCreateBody(input) {
+    const body = { proposedContent: input.proposedContent };
+    if (input.baseContent !== undefined) {
+        if (input.baseContent === input.proposedContent) {
+            throw new Error("No changes to propose — the working SKILL.md matches its base.");
+        }
+        body.baseContent = input.baseContent;
+    }
+    else {
+        body.baseContentHash = sha256Hex(input.proposedContent);
+    }
+    const note = input.note?.trim();
+    if (note)
+        body.authorNote = note;
+    return body;
+}
+/**
+ * Map an hq-pro skill route error to a single user-facing line. Pure so the
+ * status → copy mapping is unit-tested independently of the network. Prefers the
+ * server's own `error` / `message` (they carry the actionable specifics — e.g.
+ * "Skill not found", "You need write access to this skill…").
+ */
+export function mapSkillError(status, body) {
+    const server = (typeof body.error === "string" && body.error) ||
+        (typeof body.message === "string" && body.message) ||
+        "";
+    if (status === 401)
+        return "Not authenticated — please run `hq login`";
+    if (status === 403)
+        return server || "Not authorized";
+    if (status === 404)
+        return server || "Not found";
+    if (status === 409)
+        return server || "Conflict — please retry";
+    if (status === 422)
+        return server || "Company vault not provisioned";
+    if (status >= 500)
+        return `Server error: ${server || status}`;
+    return server || `Request failed (${status})`;
+}
+function shortDate(iso) {
+    return typeof iso === "string" ? iso.slice(0, 10) : "";
+}
+/**
+ * Render the review inbox as a table (one row per suggestion), optionally
+ * printing each suggestion's unified diff (or full proposed file, when the base
+ * drifted / the proposal is full-file) beneath its row. Pure → snapshot-testable.
+ */
+export function formatSuggestionsList(suggestions, opts = {}) {
+    if (suggestions.length === 0) {
+        return chalk.gray("No suggestions match — the review inbox is empty.");
+    }
+    const idW = Math.max(13, ...suggestions.map((s) => s.suggestionId.length));
+    const skillW = Math.max(8, ...suggestions.map((s) => s.skillUid.length));
+    const authW = Math.max(6, ...suggestions.map((s) => s.authorPersonUid.length));
+    const statusW = Math.max(6, ...suggestions.map((s) => s.status.length));
+    const lines = [];
+    lines.push(chalk.bold([
+        "SUGGESTION_ID".padEnd(idW),
+        "SKILL".padEnd(skillW),
+        "AUTHOR".padEnd(authW),
+        "STATUS".padEnd(statusW),
+        "BASE",
+        "CREATED",
+    ].join("  ")));
+    for (const s of suggestions) {
+        lines.push([
+            s.suggestionId.padEnd(idW),
+            s.skillUid.padEnd(skillW),
+            s.authorPersonUid.padEnd(authW),
+            s.status.padEnd(statusW),
+            s.baseChanged ? chalk.yellow("changed") : "ok".padEnd(7),
+            shortDate(s.createdAt),
+        ].join("  "));
+        if (s.authorNote) {
+            lines.push(chalk.dim(`    note: ${s.authorNote}`));
+        }
+        if (opts.showDiff) {
+            const diff = s.presentation === "diff" && s.unifiedDiff
+                ? s.unifiedDiff
+                : (s.fullContent ?? "");
+            const label = s.presentation === "diff" && s.unifiedDiff
+                ? "diff"
+                : `full file${s.baseChanged ? " (base changed)" : ""}`;
+            lines.push(chalk.dim(`    ── ${label} ──`));
+            for (const dl of diff.split("\n")) {
+                lines.push(colorizeDiffLine(`    ${dl}`));
+            }
+        }
+    }
+    return lines.join("\n");
+}
+/** Colour a unified-diff line (green add / red del / dim header). Pure. */
+function colorizeDiffLine(line) {
+    const trimmed = line.trimStart();
+    if (trimmed.startsWith("+"))
+        return chalk.green(line);
+    if (trimmed.startsWith("-"))
+        return chalk.red(line);
+    if (trimmed.startsWith("@@"))
+        return chalk.cyan(line);
+    return chalk.dim(line);
+}
+// ---------------------------------------------------------------------------
+// Company slug + local skill resolution
+// ---------------------------------------------------------------------------
+/** Read `.hq/config.json`'s `activeCompany` (mirrors signals/sources). */
+export function readActiveCompanySlug(hqRoot) {
+    const configPath = path.join(hqRoot, ".hq", "config.json");
+    if (!fs.existsSync(configPath))
+        return undefined;
+    try {
+        const cfg = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+        return typeof cfg.activeCompany === "string" && cfg.activeCompany.length > 0
+            ? cfg.activeCompany
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The skill routes are keyed on the company SLUG. Precedence: explicit
+ * `--company` → `.hq/config.json` activeCompany. Throws with actionable copy
+ * when neither is available.
+ */
+export function resolveCompanySlug(flag, hqRoot = DEFAULT_HQ_ROOT) {
+    const slug = flag ?? readActiveCompanySlug(hqRoot);
+    if (!slug) {
+        throw new Error("No company specified. Pass --company <slug> (or set an active company in .hq/config.json).");
+    }
+    return slug;
+}
+/**
+ * Recursively find a SKILL.md whose frontmatter `skill_uid` equals `uid`,
+ * searching each root breadth-first with a bounded depth (skips VCS / build /
+ * dependency dirs). Returns the first match's absolute path, or null.
+ */
+export function findSkillFileByUid(roots, uid, maxDepth = 6) {
+    const SKIP = new Set([
+        "node_modules",
+        ".git",
+        "dist",
+        "build",
+        ".next",
+        "coverage",
+    ]);
+    const queue = [];
+    for (const r of roots) {
+        if (fs.existsSync(r))
+            queue.push({ dir: r, depth: 0 });
+    }
+    while (queue.length > 0) {
+        const { dir, depth } = queue.shift();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (depth < maxDepth && !SKIP.has(entry.name)) {
+                    queue.push({ dir: full, depth: depth + 1 });
+                }
+            }
+            else if (entry.isFile() && entry.name === "SKILL.md") {
+                let content;
+                try {
+                    content = fs.readFileSync(full, "utf-8");
+                }
+                catch {
+                    continue;
+                }
+                if (parseSkillUid(content) === uid)
+                    return full;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Resolve a `suggest` target (a `skl_…` uid OR a filesystem path) to the local
+ * SKILL.md, its uid, and its content. A uid is resolved by scanning the company
+ * skills dir and the cwd; a path is read directly (a directory → its SKILL.md),
+ * with the uid read from the file's frontmatter.
+ */
+export function resolveSkillTarget(target, deps) {
+    if (SKILL_UID_PATTERN.test(target)) {
+        const roots = Array.from(new Set([
+            path.join(deps.hqRoot, "companies", deps.companySlug, "skills"),
+            deps.cwd,
+        ]));
+        const filePath = findSkillFileByUid(roots, target);
+        if (!filePath) {
+            throw new Error(`Could not find a local SKILL.md with skill_uid '${target}' under ${roots.join(", ")}. ` +
+                "Pass the path to the edited SKILL.md instead.");
+        }
+        return { filePath, skillUid: target, content: fs.readFileSync(filePath, "utf-8") };
+    }
+    // Filesystem path — accept either a SKILL.md file or a directory containing one.
+    let filePath = path.resolve(deps.cwd, target);
+    if (fs.existsSync(filePath) && fs.statSync(filePath).isDirectory()) {
+        filePath = path.join(filePath, "SKILL.md");
+    }
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`No SKILL.md found at '${target}'. Pass the path to a SKILL.md (or its directory), or a skl_… uid.`);
+    }
+    const content = fs.readFileSync(filePath, "utf-8");
+    const skillUid = parseSkillUid(content);
+    if (!skillUid) {
+        throw new Error(`The SKILL.md at '${filePath}' has no skill_uid in its frontmatter — it is not registered yet. ` +
+            "Sync / reindex the skill first so it has a stable identity, then suggest against it.");
+    }
+    return { filePath, skillUid, content };
+}
+/**
+ * Read the committed (HEAD) version of a file from its git repo — the diff base
+ * for "propose my working changes". Returns null when the file is untracked, not
+ * in a repo, or git is unavailable (the caller then falls back to full-file, or
+ * errors under `--diff`). Never throws.
+ */
+export async function readGitBase(filePath) {
+    try {
+        const git = simpleGit(path.dirname(filePath));
+        const top = (await git.revparse(["--show-toplevel"])).trim();
+        const rel = path.relative(top, filePath);
+        return await git.show([`HEAD:${rel}`]);
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Network helpers
+// ---------------------------------------------------------------------------
+async function readJsonBody(res) {
+    return (await res.json().catch(() => ({})));
+}
+/** Print the mapped error for a non-2xx response and exit(1). Returns never. */
+async function failFromResponse(res) {
+    const body = await readJsonBody(res);
+    console.error(chalk.red(mapSkillError(res.status, body)));
+    process.exit(1);
+}
+function skillRoutePrefix(slug) {
+    return `/v1/files/skills/company/${encodeURIComponent(slug)}`;
+}
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+export function registerSkillCommand(program, deps = {}) {
+    const gitBase = deps.gitBase ?? readGitBase;
+    const skill = program
+        .command("skill")
+        .description("Propose, review, and merge skill changes from the terminal")
+        .option("--company <slug>", "Company slug (defaults to the active company)");
+    // ── suggest ────────────────────────────────────────────────────────────────
+    skill
+        .command("suggest <target>")
+        .description("Create a suggestion from a local SKILL.md (a skl_… uid or a path). Never blocked by a skill lock — a suggestion is always a proposal.")
+        .option("--diff", "Require a diff base (git HEAD, or --base): fail if none is found. Default falls back to a full-file proposal.")
+        .option("--base <file>", "Explicit base file to diff the working SKILL.md against")
+        .option("--note <text>", "Author note — the rationale / failure context attached to the suggestion")
+        .action(async (target, opts) => {
+        try {
+            const companySlug = resolveCompanySlug(skill.opts().company);
+            const resolved = resolveSkillTarget(target, {
+                cwd: process.cwd(),
+                hqRoot: DEFAULT_HQ_ROOT,
+                companySlug,
+            });
+            // Base resolution: explicit --base wins; otherwise diff against git
+            // HEAD when the file is tracked. No base + --diff → hard error; no
+            // base without --diff → a full-file proposal.
+            let baseContent;
+            let baseSource = "";
+            if (opts.base !== undefined) {
+                const basePath = path.resolve(process.cwd(), opts.base);
+                if (!fs.existsSync(basePath)) {
+                    console.error(chalk.red(`Base file not found: ${opts.base}`));
+                    process.exit(1);
+                }
+                baseContent = fs.readFileSync(basePath, "utf-8");
+                baseSource = opts.base;
+            }
+            else {
+                const fromGit = await gitBase(resolved.filePath);
+                if (fromGit !== null) {
+                    baseContent = fromGit;
+                    baseSource = "git HEAD";
+                }
+            }
+            if (baseContent === undefined && opts.diff) {
+                console.error(chalk.red(`--diff needs a base, but none was found for ${resolved.filePath}. ` +
+                    "Pass --base <file>, or commit a base version first."));
+                process.exit(1);
+            }
+            if (baseContent !== undefined && baseContent === resolved.content) {
+                console.error(chalk.red(`No changes to propose — the working SKILL.md matches its base (${baseSource}).`));
+                process.exit(1);
+            }
+            const body = buildSuggestionCreateBody({
+                proposedContent: resolved.content,
+                baseContent,
+                note: opts.note,
+            });
+            const token = await ensureCognitoToken();
+            const res = await vaultApiFetch({
+                token,
+                path: `${skillRoutePrefix(companySlug)}/${encodeURIComponent(resolved.skillUid)}/suggestions`,
+                method: "POST",
+                body: body,
+            });
+            if (!res.ok)
+                await failFromResponse(res);
+            const data = (await res.json());
+            console.log(chalk.green(`Suggestion created: ${data.suggestionId}`));
+            console.log(`  Skill:   ${data.skillUid}`);
+            console.log(`  Status:  ${data.status}`);
+            // AC4 — attribution is server-derived from the invoking identity.
+            console.log(`  Author:  ${data.authorPersonUid}`);
+            console.log(`  Change:  ${data.payloadFormat === "diff" ? `diff vs ${baseSource || "base"}` : "full file"}`);
+            if (data.authorNote)
+                console.log(`  Note:    ${data.authorNote}`);
+            console.log(chalk.dim(`  The skill owner can review it: hq skill review ${data.suggestionId} --accept|--decline`));
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    // ── list-suggestions ─────────────────────────────────────────────────────────
+    skill
+        .command("list-suggestions")
+        .description("List the review inbox — open suggestions on skills you own (or one skill via --skill)")
+        .option("--skill <skillUid>", "Scope to one skill (skl_…); requires write access on it")
+        .option("--status <status>", "open | accepted | declined | all (default: open)")
+        .option("--show-diff", "Print each suggestion's unified diff / proposed file")
+        .option("--json", "Emit raw JSON instead of a table")
+        .action(async (opts) => {
+        try {
+            const companySlug = resolveCompanySlug(skill.opts().company);
+            const status = (opts.status ?? "open");
+            if (!VALID_LIST_STATUSES.includes(status)) {
+                console.error(chalk.red(`Invalid --status '${opts.status}': must be one of ${VALID_LIST_STATUSES.join(", ")}`));
+                process.exit(1);
+            }
+            if (opts.skill !== undefined && !SKILL_UID_PATTERN.test(opts.skill)) {
+                console.error(chalk.red(`Invalid --skill '${opts.skill}': must be a skl_… uid`));
+                process.exit(1);
+            }
+            const body = { status };
+            if (opts.skill !== undefined)
+                body.skillUid = opts.skill;
+            const token = await ensureCognitoToken();
+            const res = await vaultApiFetch({
+                token,
+                path: `${skillRoutePrefix(companySlug)}/suggestions/list`,
+                method: "POST",
+                body,
+            });
+            if (!res.ok)
+                await failFromResponse(res);
+            const data = (await res.json());
+            if (opts.json) {
+                console.log(JSON.stringify(data, null, 2));
+                return;
+            }
+            console.log(formatSuggestionsList(data.suggestions, { showDiff: opts.showDiff }));
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    // ── review ─────────────────────────────────────────────────────────────────
+    skill
+        .command("review <suggestionId>")
+        .description("Accept (merge) or decline a pending suggestion")
+        .option("--accept", "Accept the suggestion — merges the proposed change into the skill")
+        .option("--decline", "Decline the suggestion — leaves the skill unchanged")
+        .option("--reason <text>", "Reason recorded on a decline")
+        .option("--skill <skillUid>", "Scope the lookup to one skill (skl_…)")
+        .option("--acknowledge-base-changed", "On accept: overwrite with the full proposed file even if the skill changed since the suggestion")
+        .action(async (suggestionId, opts) => {
+        try {
+            if (!SUGGESTION_ID_PATTERN.test(suggestionId)) {
+                console.error(chalk.red(`Invalid suggestion id '${suggestionId}': must be a sgn_… id`));
+                process.exit(1);
+            }
+            const accept = opts.accept === true;
+            const decline = opts.decline === true;
+            if (accept === decline) {
+                console.error(chalk.red("Pass exactly one of --accept or --decline."));
+                process.exit(1);
+            }
+            if (opts.skill !== undefined && !SKILL_UID_PATTERN.test(opts.skill)) {
+                console.error(chalk.red(`Invalid --skill '${opts.skill}': must be a skl_… uid`));
+                process.exit(1);
+            }
+            const companySlug = resolveCompanySlug(skill.opts().company);
+            const token = await ensureCognitoToken();
+            // Resolve the suggestion's skillUid + live path from the SAME LIST route
+            // the console uses — accept/decline are path↔uid guarded, so the path
+            // must come from the authoritative row, never guessed. `all` so an
+            // already-resolved suggestion yields a precise "already <status>" error.
+            const listBody = { status: "all" };
+            if (opts.skill !== undefined)
+                listBody.skillUid = opts.skill;
+            const listRes = await vaultApiFetch({
+                token,
+                path: `${skillRoutePrefix(companySlug)}/suggestions/list`,
+                method: "POST",
+                body: listBody,
+            });
+            if (!listRes.ok)
+                await failFromResponse(listRes);
+            const { suggestions } = (await listRes.json());
+            const row = suggestions.find((s) => s.suggestionId === suggestionId);
+            if (!row) {
+                console.error(chalk.red(`Suggestion ${suggestionId} is not in your review inbox. ` +
+                    "If it targets a skill you don't own, scope the lookup with --skill <skl_…>."));
+                process.exit(1);
+            }
+            if (row.status !== "open") {
+                console.error(chalk.yellow(`Suggestion ${suggestionId} is already ${row.status} — nothing to do.`));
+                process.exit(1);
+            }
+            if (accept) {
+                if (!row.path) {
+                    console.error(chalk.red("Could not resolve the live skill path for this suggestion — the skill may have been removed."));
+                    process.exit(1);
+                }
+                const acceptBody = { path: row.path };
+                if (opts.acknowledgeBaseChanged)
+                    acceptBody.acknowledgeBaseChanged = true;
+                const res = await vaultApiFetch({
+                    token,
+                    path: `${skillRoutePrefix(companySlug)}/${encodeURIComponent(row.skillUid)}/suggestions/${encodeURIComponent(suggestionId)}/accept`,
+                    method: "POST",
+                    body: acceptBody,
+                });
+                if (!res.ok) {
+                    const errBody = await readJsonBody(res);
+                    // AC4 (US-009): the base drifted — guide the operator to re-run
+                    // with acknowledgement rather than silently overwriting.
+                    if (res.status === 409 &&
+                        errBody.code === "WRITE_SKILL_SUGGESTION_BASE_CHANGED") {
+                        console.error(chalk.yellow("The skill changed since this suggestion was written. Re-run with " +
+                            "--acknowledge-base-changed to overwrite it with the full proposed file."));
+                        process.exit(1);
+                    }
+                    console.error(chalk.red(mapSkillError(res.status, errBody)));
+                    process.exit(1);
+                }
+                const data = (await res.json());
+                console.log(chalk.green("Suggestion accepted — merged and closed."));
+                console.log(`  Skill:       ${data.skillUid}`);
+                console.log(`  Suggestion:  ${data.suggestionId}`);
+                console.log(`  Accepted by: ${data.acceptedBy}`);
+                return;
+            }
+            // Decline.
+            const declineBody = {};
+            if (opts.reason !== undefined)
+                declineBody.reason = opts.reason;
+            const res = await vaultApiFetch({
+                token,
+                path: `${skillRoutePrefix(companySlug)}/${encodeURIComponent(row.skillUid)}/suggestions/${encodeURIComponent(suggestionId)}/decline`,
+                method: "POST",
+                body: declineBody,
+            });
+            if (!res.ok)
+                await failFromResponse(res);
+            const data = (await res.json());
+            console.log(chalk.green("Suggestion declined — the skill was left unchanged."));
+            console.log(`  Skill:       ${data.skillUid}`);
+            console.log(`  Suggestion:  ${data.suggestionId}`);
+            console.log(`  Declined by: ${data.declinedBy}`);
+            if (data.reason)
+                console.log(`  Reason:      ${data.reason}`);
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    return skill;
+}
+//# sourceMappingURL=skill.js.map
+//# debugId=5bdf8a18-3088-5615-b596-9be2c9fdb5cc

package/dist/commands/workers.d.ts

@@ -0,0 +1,48 @@
+import { Command } from "commander";
+export interface RegistryWorker {
+    id: string;
+    path: string;
+    type: string;
+    visibility: string;
+    company?: string;
+    team?: string;
+    status?: string;
+    description?: string;
+    triggers?: string;
+    grants?: string;
+}
+/** Read + parse the worker registry. Empty array if it does not exist. */
+export declare function readWorkerRegistry(hqRoot: string): RegistryWorker[];
+/**
+ * Best-effort active company: workspace/sessions/.current -> meta.yaml
+ * company_slug. Undefined when no session context is set. Pure/read-only.
+ */
+export declare function resolveActiveCompany(hqRoot: string): string | undefined;
+/**
+ * Membership-aware access filter for worker discovery: public workers always;
+ * company workers only for the active company. Mirrors the /run skill and the
+ * inject-worker-suggestion hook so all three surfaces agree.
+ */
+export declare function filterAccessibleWorkers(workers: RegistryWorker[], activeCompany: string | undefined): RegistryWorker[];
+/**
+ * The company-relative vault prefix for a worker, e.g.
+ * companies/indigo/workers/deal-brain/ -> workers/deal-brain/. Returns null for
+ * a worker with no company (public/shared — not shareable via ACL).
+ */
+export declare function workerVaultPrefix(w: RegistryWorker): string | null;
+export type GranteeType = "company-wide" | "email" | "group";
+export interface ClassifiedPrincipal {
+    granteeType: GranteeType;
+    granteeId: string;
+    label: string;
+}
+/** Classify a share principal (@all | email | grp_*) — null when invalid. */
+export declare function classifyPrincipal(principal: string): ClassifiedPrincipal | null;
+/**
+ * Record a grant locally in the worker's tool-owned .grants.yaml sidecar. Kept
+ * out of worker.yaml so we never rewrite a hand-authored file; the registry
+ * generator unions this sidecar into the registry `grants:` field. Idempotent.
+ */
+export declare function writeGrantSidecar(hqRoot: string, workerPath: string, principalLabel: string): void;
+export declare function registerWorkersCommand(program: Command): void;
+//# sourceMappingURL=workers.d.ts.map