@indigoai-us/hq-cli 5.31.0 → 5.32.0

package/dist/utils/pack-contributions.js

@@ -0,0 +1,239 @@
+/**
+ * Content-pack contribution helpers -- the single source of truth (in TS) for
+ * the `contributes.* -> host-path` symlink mapping that `hq install` wires via
+ * `core/scripts/scan-packages.sh`.
+ *
+ * `pack-install.ts` only INSTALLS content packs (into `core/packages/<name>/`,
+ * tracked by filesystem presence -- there is no registry file). The list /
+ * update / uninstall lifecycle in `commands/packs.ts` needs to reason about the
+ * SAME mapping so it can report link health and cleanly un-wire a pack without
+ * leaving dangling symlinks. That mapping is duplicated today in two places:
+ *
+ *   - core/scripts/scan-packages.sh  (bash `case`, the wiring authority)
+ *   - pack-install.ts validateManifest's `subpaths` record (payload validation)
+ *
+ * This module re-encodes it once for TS callers. A parity test
+ * (`pack-contributions.test.ts`) asserts it matches scan-packages.sh's `case`
+ * arms so the three copies cannot drift.
+ */
+
+!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]="f5492359-fdf3-5e85-9a81-699c4cd68f6a")}catch(e){}}();
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+/**
+ * Map one contributes entry to its source/host paths. MUST stay in lockstep
+ * with scan-packages.sh:wire_one_package and pack-install.ts:validateManifest.
+ */
+function linkFor(hqRoot, packDir, key, item) {
+    let srcRel;
+    let dstRel;
+    switch (key) {
+        case 'workers':
+            srcRel = path.join('workers', item);
+            dstRel = path.join('core', 'workers', 'public', item);
+            break;
+        case 'knowledge':
+            srcRel = path.join('knowledge', item);
+            dstRel = path.join('core', 'knowledge', 'public', item);
+            break;
+        case 'skills':
+            srcRel = path.join('skills', item);
+            dstRel = path.join('.claude', 'skills', item);
+            break;
+        case 'commands':
+            srcRel = path.join('commands', `${item}.md`);
+            dstRel = path.join('.claude', 'commands', `${item}.md`);
+            break;
+        case 'hooks':
+            srcRel = path.join('hooks', `${item}.sh`);
+            dstRel = path.join('.claude', 'hooks', `${item}.sh`);
+            break;
+        case 'policies':
+            srcRel = path.join('policies', `${item}.md`);
+            dstRel = path.join('core', 'policies', `${item}.md`);
+            break;
+        case 'scripts':
+            srcRel = path.join('scripts', item);
+            dstRel = path.join('core', 'scripts', item);
+            break;
+    }
+    return {
+        key,
+        item,
+        src: path.join(packDir, srcRel),
+        dst: path.join(hqRoot, dstRel),
+    };
+}
+/**
+ * Every symlink a pack's `contributes` block declares. Empty subfields and
+ * non-array values are ignored, mirroring scan-packages.sh.
+ */
+export function contributionLinks(hqRoot, packDir, contributes) {
+    const links = [];
+    for (const [key, items] of Object.entries(contributes)) {
+        if (!Array.isArray(items))
+            continue;
+        for (const item of items) {
+            if (typeof item !== 'string' || item.length === 0)
+                continue;
+            links.push(linkFor(hqRoot, packDir, key, item));
+        }
+    }
+    return links;
+}
+/** Classify a host path against the link that should own it. */
+export function linkStatus(link) {
+    let st;
+    try {
+        st = fs.lstatSync(link.dst);
+    }
+    catch {
+        return 'missing';
+    }
+    if (!st.isSymbolicLink()) {
+        return 'foreign'; // a real file/dir occupies the slot -- not ours
+    }
+    let target;
+    try {
+        target = fs.readlinkSync(link.dst);
+    }
+    catch {
+        return 'foreign';
+    }
+    // scan-packages.sh writes the symlink target as the absolute `src` path, so a
+    // direct compare is correct. Resolve both to be robust to trailing slashes.
+    const resolvedTarget = path.resolve(path.dirname(link.dst), target);
+    if (path.resolve(link.src) !== resolvedTarget) {
+        return 'foreign'; // points at another pack / somewhere else
+    }
+    return fs.existsSync(link.src) ? 'live' : 'broken';
+}
+/** Absolute path to `<hqRoot>/core/packages`. */
+export function packagesDir(hqRoot) {
+    return path.join(hqRoot, 'core', 'packages');
+}
+/** Read and shallowly validate a pack's package.yaml. */
+export function readPackManifest(packDir) {
+    const manifestPath = path.join(packDir, 'package.yaml');
+    if (!fs.existsSync(manifestPath)) {
+        return { manifest: null, error: 'package.yaml missing' };
+    }
+    try {
+        const parsed = yaml.load(fs.readFileSync(manifestPath, 'utf-8'));
+        if (!parsed || typeof parsed !== 'object') {
+            return { manifest: null, error: 'package.yaml is not a mapping' };
+        }
+        return { manifest: parsed };
+    }
+    catch (e) {
+        return { manifest: null, error: `package.yaml invalid: ${e.message}` };
+    }
+}
+/**
+ * Walk `core/packages/<name>/package.yaml`. Skips the `.archive` dir, the bundled
+ * `README.md`, and any non-directory entry. Filesystem presence is the source
+ * of truth for installed content packs.
+ */
+export function listInstalledPacks(hqRoot) {
+    const dir = packagesDir(hqRoot);
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const name of fs.readdirSync(dir).sort()) {
+        if (name.startsWith('.'))
+            continue; // .archive, .DS_Store, etc.
+        const packDir = path.join(dir, name);
+        let st;
+        try {
+            st = fs.statSync(packDir);
+        }
+        catch {
+            continue;
+        }
+        if (!st.isDirectory())
+            continue; // README.md and friends
+        const { manifest, error } = readPackManifest(packDir);
+        if (!manifest && !fs.existsSync(path.join(packDir, 'package.yaml'))) {
+            continue; // a plain dir that isn't a pack -- ignore silently
+        }
+        out.push({ name, dir: packDir, manifest, error });
+    }
+    return out;
+}
+/**
+ * Remove only the host symlinks that resolve into THIS pack's directory
+ * (status `live` or `broken`). Foreign links and real files are left in place
+ * -- same collision philosophy as scan-packages.sh. This is what prevents an
+ * uninstall from leaving dangling symlinks behind.
+ */
+export function unwirePack(hqRoot, packDir, contributes) {
+    const result = { unlinked: [], skipped: [] };
+    for (const link of contributionLinks(hqRoot, packDir, contributes)) {
+        const status = linkStatus(link);
+        if (status === 'live' || status === 'broken') {
+            try {
+                fs.unlinkSync(link.dst);
+                result.unlinked.push({ key: link.key, item: link.item, dst: link.dst });
+            }
+            catch {
+                result.skipped.push({
+                    key: link.key,
+                    item: link.item,
+                    dst: link.dst,
+                    reason: 'foreign',
+                });
+            }
+        }
+        else {
+            result.skipped.push({
+                key: link.key,
+                item: link.item,
+                dst: link.dst,
+                reason: status === 'missing' ? 'missing' : 'foreign',
+            });
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Host introspection: hqVersion + recommended_packages catalog
+// ---------------------------------------------------------------------------
+/** Locate core.yaml -- v14+ nests it under `core/`, older layouts at the root. */
+function coreYamlPath(hqRoot) {
+    const nested = path.join(hqRoot, 'core', 'core.yaml');
+    if (fs.existsSync(nested))
+        return nested;
+    const flat = path.join(hqRoot, 'core.yaml');
+    if (fs.existsSync(flat))
+        return flat;
+    return null;
+}
+export function readHqVersion(hqRoot) {
+    const p = coreYamlPath(hqRoot);
+    if (!p)
+        return null;
+    try {
+        const c = yaml.load(fs.readFileSync(p, 'utf-8'));
+        return c?.hqVersion ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read `recommended_packages` from core.yaml (the curated content-pack catalog). */
+export function readRecommendedPackages(hqRoot) {
+    const p = coreYamlPath(hqRoot);
+    if (!p)
+        return [];
+    try {
+        const c = yaml.load(fs.readFileSync(p, 'utf-8'));
+        const list = c?.recommended_packages;
+        return Array.isArray(list) ? list : [];
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=pack-contributions.js.map
+//# debugId=f5492359-fdf3-5e85-9a81-699c4cd68f6a

package/package.json

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

package/src/commands/group-grants.test.ts

@@ -0,0 +1,291 @@
+/**
+ * Unit tests for `hq group-grants grant|revoke|outbound|inbound`
+ * (group-grants.ts).
+ *
+ * Mirrors members.test.ts: mock `globalThis.fetch`, exercise the exported
+ * helper functions, assert the request body the client sends, and assert HTTP
+ * errors (esp. 403 cross-tenant) are wrapped + surfaced actionably.
+ *
+ * Covers the two story e2e behaviors:
+ *   1. Operator WITH invite rights on B grants (G, B, member) → client POSTs
+ *      /group-grants with {groupId:G, sourceCompanyUid, targetCompanyUid:B,
+ *      role:'member'} and returns the grant.
+ *   2. Operator with NO role on independent C grants (G, C) → backend 403 →
+ *      helper throws GrantHttpError(403, FORBIDDEN) and formatGrantHttpError
+ *      yields an actionable cross-tenant permission message.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi, type MockInstance } from "vitest";
+
+import {
+  GrantHttpError,
+  formatGrantHttpError,
+  grantGroup,
+  listInboundGrants,
+  listOutboundGrants,
+  revokeGroupGrant,
+} from "./group-grants.js";
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+let fetchSpy: MockInstance<typeof fetch>;
+
+beforeEach(() => {
+  fetchSpy = vi.spyOn(globalThis, "fetch");
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// grantGroup — story e2e #1 (authorized) + validation
+// ---------------------------------------------------------------------------
+
+describe("grantGroup", () => {
+  it("POSTs /group-grants with the right body and returns the grant (operator with invite rights on B)", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        grant: {
+          groupId: "grp_eng",
+          sourceCompanyUid: "cmp_a",
+          targetCompanyUid: "cmp_b",
+          role: "member",
+        },
+      }),
+    );
+
+    const grant = await grantGroup({
+      groupId: "grp_eng",
+      sourceCompanyUid: "cmp_a",
+      targetCompanyUid: "cmp_b",
+      role: "member",
+      token: "test-token",
+    });
+
+    expect(grant.role).toBe("member");
+    expect(grant.targetCompanyUid).toBe("cmp_b");
+
+    const call = fetchSpy.mock.calls[0];
+    expect(String(call[0])).toContain("/group-grants");
+    expect(call[1]?.method).toBe("POST");
+    const body = JSON.parse((call[1]?.body as string) ?? "{}");
+    expect(body).toEqual({
+      groupId: "grp_eng",
+      sourceCompanyUid: "cmp_a",
+      targetCompanyUid: "cmp_b",
+      role: "member",
+    });
+  });
+
+  it("synthesizes a grant when the server omits the grant body", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
+
+    const grant = await grantGroup({
+      groupId: "grp_eng",
+      sourceCompanyUid: "cmp_a",
+      targetCompanyUid: "cmp_b",
+      role: "admin",
+      token: "test-token",
+    });
+
+    expect(grant).toEqual({
+      groupId: "grp_eng",
+      sourceCompanyUid: "cmp_a",
+      targetCompanyUid: "cmp_b",
+      role: "admin",
+    });
+  });
+
+  it("wraps a 403 in GrantHttpError carrying the FORBIDDEN code (operator with no role on independent C)", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(403, { error: "forbidden", code: "FORBIDDEN" }),
+    );
+
+    const err = await grantGroup({
+      groupId: "grp_eng",
+      sourceCompanyUid: "cmp_a",
+      targetCompanyUid: "cmp_c",
+      role: "member",
+      token: "test-token",
+    }).catch((e) => e);
+
+    expect(err).toBeInstanceOf(GrantHttpError);
+    expect((err as GrantHttpError).status).toBe(403);
+    expect((err as GrantHttpError).code).toBe("FORBIDDEN");
+  });
+
+  it("rejects an invalid group id before calling the API", async () => {
+    await expect(
+      grantGroup({
+        groupId: "eng",
+        sourceCompanyUid: "cmp_a",
+        targetCompanyUid: "cmp_b",
+        role: "member",
+        token: "test-token",
+      }),
+    ).rejects.toThrow(/Invalid group id/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("rejects an unknown role before calling the API", async () => {
+    await expect(
+      grantGroup({
+        groupId: "grp_eng",
+        sourceCompanyUid: "cmp_a",
+        targetCompanyUid: "cmp_b",
+        role: "superuser",
+        token: "test-token",
+      }),
+    ).rejects.toThrow(/Invalid role/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("rejects a same-company grant before calling the API", async () => {
+    await expect(
+      grantGroup({
+        groupId: "grp_eng",
+        sourceCompanyUid: "cmp_a",
+        targetCompanyUid: "cmp_a",
+        role: "member",
+        token: "test-token",
+      }),
+    ).rejects.toThrow(/cross company boundaries/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// formatGrantHttpError — actionable cross-tenant messaging (story AC #3)
+// ---------------------------------------------------------------------------
+
+describe("formatGrantHttpError", () => {
+  it("renders an actionable cross-tenant 403 message naming the target company", () => {
+    const msg = formatGrantHttpError(403, "forbidden", {
+      targetCompany: "acme-c",
+      code: "FORBIDDEN",
+    });
+    expect(msg).toMatch(/Permission denied/);
+    expect(msg).toMatch(/owner or admin of the target company 'acme-c'/);
+  });
+
+  it("maps 401 to a login hint", () => {
+    expect(formatGrantHttpError(401, "x")).toMatch(/hq login/);
+  });
+
+  it("passes through a generic 400 message", () => {
+    expect(formatGrantHttpError(400, "bad role")).toBe("bad role");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// revokeGroupGrant
+// ---------------------------------------------------------------------------
+
+describe("revokeGroupGrant", () => {
+  it("POSTs /group-grants/revoke with the right body", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { revoked: true }));
+
+    await revokeGroupGrant({
+      groupId: "grp_eng",
+      sourceCompanyUid: "cmp_a",
+      targetCompanyUid: "cmp_b",
+      token: "test-token",
+    });
+
+    const call = fetchSpy.mock.calls[0];
+    expect(String(call[0])).toContain("/group-grants/revoke");
+    expect(call[1]?.method).toBe("POST");
+    const body = JSON.parse((call[1]?.body as string) ?? "{}");
+    expect(body).toEqual({
+      groupId: "grp_eng",
+      sourceCompanyUid: "cmp_a",
+      targetCompanyUid: "cmp_b",
+    });
+  });
+
+  it("wraps a 403 in GrantHttpError", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(403, { error: "forbidden", code: "FORBIDDEN" }),
+    );
+
+    await expect(
+      revokeGroupGrant({
+        groupId: "grp_eng",
+        sourceCompanyUid: "cmp_a",
+        targetCompanyUid: "cmp_c",
+        token: "test-token",
+      }),
+    ).rejects.toBeInstanceOf(GrantHttpError);
+  });
+
+  it("rejects an invalid group id before calling the API", async () => {
+    await expect(
+      revokeGroupGrant({
+        groupId: "eng",
+        sourceCompanyUid: "cmp_a",
+        targetCompanyUid: "cmp_b",
+        token: "test-token",
+      }),
+    ).rejects.toThrow(/Invalid group id/);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// listOutboundGrants / listInboundGrants
+// ---------------------------------------------------------------------------
+
+describe("listOutboundGrants", () => {
+  it("GETs /group-grants/outbound with sourceCompanyUid and optional groupId", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        grants: [
+          {
+            groupId: "grp_eng",
+            sourceCompanyUid: "cmp_a",
+            targetCompanyUid: "cmp_b",
+            role: "member",
+          },
+        ],
+      }),
+    );
+
+    const list = await listOutboundGrants("test-token", "cmp_a", "grp_eng");
+    expect(list).toHaveLength(1);
+
+    const url = new URL(String(fetchSpy.mock.calls[0][0]));
+    expect(url.pathname).toContain("/group-grants/outbound");
+    expect(url.searchParams.get("sourceCompanyUid")).toBe("cmp_a");
+    expect(url.searchParams.get("groupId")).toBe("grp_eng");
+  });
+
+  it("returns [] when the server returns no grants", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, {}));
+    expect(await listOutboundGrants("test-token", "cmp_a")).toEqual([]);
+  });
+});
+
+describe("listInboundGrants", () => {
+  it("GETs /group-grants/inbound with companyUid", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { grants: [] }));
+
+    await listInboundGrants("test-token", "cmp_b");
+
+    const url = new URL(String(fetchSpy.mock.calls[0][0]));
+    expect(url.pathname).toContain("/group-grants/inbound");
+    expect(url.searchParams.get("companyUid")).toBe("cmp_b");
+  });
+
+  it("wraps a 403 in GrantHttpError", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(403, { error: "forbidden" }));
+    await expect(
+      listInboundGrants("test-token", "cmp_b"),
+    ).rejects.toBeInstanceOf(GrantHttpError);
+  });
+});