@indigoai-us/hq-cli 5.32.0 → 5.33.1

package/src/commands/publish.ts

@@ -0,0 +1,517 @@
+/**
+ * hq publish <skill-or-worker-path> — marketplace packer + authenticated upload
+ * (US-004, hq-creator-marketplace).
+ *
+ * Flow:
+ *   1. Refuse if not logged in (cached Cognito session absent/expired) — uploads
+ *      nothing. The author uid is read from the cached idToken's `sub`.
+ *   2. Validate package.yaml with the canonical 10-rule validator
+ *      (`validateManifest` from pack-install.ts) — never duplicate that logic.
+ *      On failure, print the validation error and upload nothing.
+ *   3. Stamp `author` (uid from the idToken `sub`, plus handle/displayName) into
+ *      the pack's package.yaml (AC1). The server re-derives author from the
+ *      Cognito sub too, but the CLI stamps it so the on-disk + published pack
+ *      carry attribution.
+ *   4. Tar (gzip) the payload, base64-encode the bytes, and POST a JSON body to
+ *      `/v1/listings` via vaultApiFetch with the access token. The deployed
+ *      server JSON.parses the body and expects
+ *      { type, name, slug, version, summary?, contributes(string)?,
+ *        creatorHandle?, tarball(base64) }, returning the created listing id +
+ *      `pending_review` status. A 409 (re-publishing the same version) is
+ *      surfaced as a clear duplicate error.
+ *   5. Register/update `modules.yaml` provenance for the published source.
+ *
+ * Reuses the existing CLI plumbing:
+ *   - cognito-session.ts (token cache / access token)
+ *   - vault-api.ts (vaultApiFetch — authed JSON POST to /v1/listings)
+ *   - pack-install.ts:validateManifest (the 10 validation rules)
+ *   - manifest.ts (modules.yaml read/write for provenance)
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import { execFileSync } from 'child_process';
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { loadCachedTokens, isExpiring } from '@indigoai-us/hq-cloud';
+import { ensureCognitoToken } from '../utils/cognito-session.js';
+import { vaultApiFetch } from '../utils/vault-api.js';
+import { validateManifest } from './pack-install.js';
+import { findHqRoot, readManifest, writeManifest } from '../utils/manifest.js';
+import type { PackManifest, PackModuleDefinition, ModulesManifest } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// Identity
+// ---------------------------------------------------------------------------
+
+export interface IdTokenClaims {
+  sub?: string;
+  email?: string;
+  /** Cognito custom attributes / standard claims used for attribution. */
+  'cognito:username'?: string;
+  preferred_username?: string;
+  name?: string;
+}
+
+/**
+ * Decode a Cognito idToken's payload (no signature verification — this is a
+ * local read of an already-trusted cached token, mirroring whoami.ts/login.ts).
+ * Pure → unit-testable.
+ */
+export function peekIdToken(idToken: string): IdTokenClaims {
+  try {
+    const payload = idToken.split('.')[1];
+    if (!payload) return {};
+    const pad = payload.length % 4 === 0 ? '' : '='.repeat(4 - (payload.length % 4));
+    const normalized = payload.replace(/-/g, '+').replace(/_/g, '/') + pad;
+    const decoded = JSON.parse(Buffer.from(normalized, 'base64').toString('utf-8'));
+    return decoded as IdTokenClaims;
+  } catch {
+    return {};
+  }
+}
+
+export interface ResolvedAuthor {
+  uid: string;
+  handle: string;
+  displayName: string;
+}
+
+/**
+ * Build the pack `author` block from idToken claims. `uid` is the Cognito
+ * `sub` (AC1). `handle`/`displayName` fall back gracefully so a thin token
+ * still produces a well-shaped author that passes `validateManifest`. Throws
+ * if there is no `sub` (caller is treated as logged-out). Pure.
+ */
+export function resolveAuthor(claims: IdTokenClaims): ResolvedAuthor {
+  const uid = claims.sub?.trim();
+  if (!uid) {
+    throw new Error('Cached session has no subject (sub) claim — run `hq login` again.');
+  }
+  const handle =
+    claims.preferred_username?.trim() ||
+    claims['cognito:username']?.trim() ||
+    claims.email?.split('@')[0]?.trim() ||
+    uid;
+  const displayName =
+    claims.name?.trim() || claims.email?.trim() || handle;
+  return { uid, handle, displayName };
+}
+
+// ---------------------------------------------------------------------------
+// package.yaml author stamping
+// ---------------------------------------------------------------------------
+
+/**
+ * Stamp `author` into a parsed manifest object, returning the YAML text to
+ * write. Existing `author` is overwritten with the resolved attribution so the
+ * publisher's own identity always wins (the server enforces this too). Pure.
+ */
+export function stampAuthorYaml(
+  manifest: Record<string, unknown>,
+  author: ResolvedAuthor,
+): string {
+  const stamped = { ...manifest, author };
+  return yaml.dump(stamped, { lineWidth: -1 });
+}
+
+/** Read package.yaml, stamp author, write it back. Returns the stamped author. */
+export function stampAuthorIntoPackage(
+  payloadDir: string,
+  author: ResolvedAuthor,
+): void {
+  const manifestPath = path.join(payloadDir, 'package.yaml');
+  const parsed = yaml.load(fs.readFileSync(manifestPath, 'utf-8')) as Record<string, unknown>;
+  fs.writeFileSync(manifestPath, stampAuthorYaml(parsed, author));
+}
+
+// ---------------------------------------------------------------------------
+// Tarball
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a gzipped tarball of `payloadDir` and return its bytes. Uses the same
+ * `tar` argv approach as pack-install.ts (no shell, no new dep). The archive is
+ * written to a tmp file, read back, then removed.
+ */
+export function tarballPayload(payloadDir: string): Uint8Array {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hq-publish-tar-'));
+  const tarPath = path.join(tmpDir, 'pack.tar.gz');
+  try {
+    // `-C payloadDir .` packs the directory contents at the archive root
+    // (package.yaml + skills/ etc. at top level), excluding VCS/junk.
+    execFileSync(
+      'tar',
+      [
+        '-czf',
+        tarPath,
+        '-C',
+        payloadDir,
+        '--exclude=.git',
+        '--exclude=node_modules',
+        '--exclude=.DS_Store',
+        '.',
+      ],
+      { stdio: ['ignore', 'ignore', 'inherit'] },
+    );
+    return fs.readFileSync(tarPath);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Server-contract field derivation (POST /v1/listings, JSON body)
+// ---------------------------------------------------------------------------
+
+/** The marketplace listing type the server enforces (VALID_TYPES). */
+export type ListingType = 'skill' | 'worker';
+
+/**
+ * Infer the listing `type` the server requires (exactly "skill" | "worker").
+ *
+ * Rules:
+ *   - An explicit `type` hint in package.yaml wins if it is already a valid
+ *     listing type (lets a pack author override the inference deterministically).
+ *   - Otherwise: a pack that contributes workers → "worker"; one that
+ *     contributes skills → "skill".
+ *   - Ambiguous/both/neither → "skill" (the documented default).
+ * Pure → unit-testable.
+ */
+export function inferListingType(pkg: PackManifest): ListingType {
+  const hint = (pkg as unknown as { type?: unknown }).type;
+  if (hint === 'skill' || hint === 'worker') return hint;
+
+  const contributes = pkg.contributes ?? {};
+  const hasWorkers = (contributes.workers?.length ?? 0) > 0;
+  const hasSkills = (contributes.skills?.length ?? 0) > 0;
+
+  // Prefer skill when ambiguous (both) or when neither is present.
+  if (hasWorkers && !hasSkills) return 'worker';
+  return 'skill';
+}
+
+/**
+ * Derive the marketplace slug from the pack name. By convention pack names are
+ * `^hq-pack-[a-z0-9][a-z0-9-]*$`, so we strip the leading `hq-pack-` to get a
+ * short, valid, non-empty slug (e.g. `hq-pack-demo` → `demo`). If the name does
+ * not carry that prefix we fall back to the full name. Pure.
+ */
+export function deriveSlug(packName: string): string {
+  const stripped = packName.replace(/^hq-pack-/, '');
+  return stripped.length > 0 ? stripped : packName;
+}
+
+/**
+ * Build the SHORT STRING `contributes` summary the server expects (it stores a
+ * string, NOT the structured object). Lists each non-empty contribute category
+ * with its entries, e.g. "workers: alpha, beta; skills: demo". Pure.
+ */
+export function summarizeContributes(
+  contributes: PackManifest['contributes'],
+): string {
+  const parts: string[] = [];
+  for (const [key, entries] of Object.entries(contributes ?? {})) {
+    if (Array.isArray(entries) && entries.length > 0) {
+      parts.push(`${key}: ${entries.join(', ')}`);
+    }
+  }
+  return parts.join('; ');
+}
+
+// ---------------------------------------------------------------------------
+// Provenance — modules.yaml upsert
+// ---------------------------------------------------------------------------
+
+/**
+ * Register or update a `package`-strategy module entry in modules.yaml so the
+ * published source has on-disk provenance (AC4). Returns the updated manifest.
+ * Pure (operates on an in-memory manifest); the disk read/write is done by the
+ * caller via `recordProvenance`.
+ */
+export function upsertPackProvenance(
+  manifest: ModulesManifest | null,
+  entry: PackModuleDefinition,
+): ModulesManifest {
+  const next: ModulesManifest = manifest ?? { version: '1', modules: [] };
+  const idx = next.modules.findIndex((m) => m.name === entry.name);
+  if (idx >= 0) {
+    next.modules[idx] = entry;
+  } else {
+    next.modules.push(entry);
+  }
+  return next;
+}
+
+/** Read modules.yaml, upsert the provenance entry, write it back. */
+export function recordProvenance(
+  hqRoot: string,
+  pkg: PackManifest,
+  source: string,
+): void {
+  const entry: PackModuleDefinition = {
+    name: pkg.name,
+    strategy: 'package',
+    source,
+    version: pkg.version,
+    installed_at_iso: new Date().toISOString(),
+    // PackManifest.access is 'public'|'private'; module AccessLevel uses
+    // 'public'|'team'|'role:*'. A private pack maps to team scope.
+    access: pkg.access === 'private' ? 'team' : 'public',
+  };
+  const updated = upsertPackProvenance(readManifest(hqRoot), entry);
+  writeManifest(hqRoot, updated);
+}
+
+// ---------------------------------------------------------------------------
+// Listing-response formatting
+// ---------------------------------------------------------------------------
+
+export interface ListingResponse {
+  id?: string;
+  listingId?: string;
+  status?: string;
+  /** Server-resolved creator handle (prefers the caller's claimed handle). */
+  creatorHandle?: string;
+}
+
+/**
+ * Unwrap the `POST /v1/listings` SUCCESS envelope. The deployed server returns
+ * the created listing WRAPPED: `{ listing: { listingId, creatorHandle, status,
+ * … } }`. Older/mocked responses return the listing fields at the TOP level.
+ * This reads `body.listing` when present and falls back to the top-level `body`
+ * for backwards-compat. Pure.
+ */
+export function unwrapListing(body: Record<string, unknown>): ListingResponse {
+  const inner = body?.listing;
+  if (inner && typeof inner === 'object') {
+    return inner as ListingResponse;
+  }
+  return body as ListingResponse;
+}
+
+/**
+ * Map a `POST /v1/listings` response into a user-facing success notice. Pure.
+ * Throws a clear error on a duplicate (409) or any non-2xx status so the caller
+ * prints it and exits non-zero.
+ *
+ * The notice uses the REAL listing id and the SERVER-resolved `creatorHandle`
+ * from the (possibly `{ listing }`-wrapped) response body — not the
+ * locally-resolved author handle — falling back gracefully when the server
+ * omits either field.
+ */
+export function buildListingNotice(
+  status: number,
+  body: Record<string, unknown>,
+  packName: string,
+  packVersion: string,
+): string {
+  if (status === 409) {
+    throw new Error(
+      `${packName}@${packVersion} is already published (duplicate version). ` +
+        `Bump the version in package.yaml and re-run \`hq publish\`.`,
+    );
+  }
+  if (status === 401 || status === 403) {
+    throw new Error('Not authorized to publish — run `hq login` and ensure your creator account is verified.');
+  }
+  if (status < 200 || status >= 300) {
+    const msg =
+      (body.error as string) ?? (body.message as string) ?? `HTTP ${status}`;
+    throw new Error(`Publish failed: ${msg}`);
+  }
+  const listing = unwrapListing(body);
+  const id = listing.listingId ?? listing.id ?? '(unknown id)';
+  const listingStatus = listing.status ?? 'pending_review';
+  const serverHandle = listing.creatorHandle?.trim();
+  const attribution = serverHandle ? ` Attributed to @${serverHandle}.` : '';
+  return `Published ${packName}@${packVersion} — listing ${id} (${listingStatus}).${attribution}`;
+}
+
+// ---------------------------------------------------------------------------
+// Publish flow (testable core)
+// ---------------------------------------------------------------------------
+
+/**
+ * The exact JSON body the deployed `POST /v1/listings` handler expects. Field
+ * shapes mirror the server contract: `type` ∈ {skill,worker}, `contributes` is
+ * a STRING summary (not the structured object), `tarball` is base64 gzip bytes.
+ */
+export interface ListingRequest {
+  type: ListingType;
+  name: string;
+  slug: string;
+  version: string;
+  summary?: string;
+  contributes?: string;
+  creatorHandle?: string;
+  /** Base64-encoded gzip pack tarball (pack.tar.gz bytes). */
+  tarball: string;
+}
+
+export interface PublishDeps {
+  /** Returns the cached idToken, or null/expired if not logged in. */
+  loadIdToken: () => string | null;
+  /** Returns a non-interactive access token. */
+  getAccessToken: () => Promise<string>;
+  /**
+   * POSTs the listing as a JSON body to `/v1/listings` and returns the parsed
+   * { status, body }. `tarball` is the BASE64-encoded gzip pack bytes — the
+   * server JSON.parses the body and base64-decodes the tarball.
+   */
+  upload: (args: {
+    token: string;
+    listing: ListingRequest;
+  }) => Promise<{ status: number; body: Record<string, unknown> }>;
+  hqRoot: string;
+  /** Reads core.yaml hqVersion for the validator (null when absent). */
+  hqVersion: string | null;
+}
+
+export interface PublishResult {
+  notice: string;
+  author: ResolvedAuthor;
+  pkg: PackManifest;
+  /** True when the success notice already carries the server's attribution. */
+  serverAttributed: boolean;
+}
+
+/**
+ * Core publish logic, dependency-injected so it can be unit-tested with mocked
+ * network + a tmp filesystem (no real API, no browser login). Returns the
+ * success notice; throws (uploading nothing) on logged-out or validation
+ * failure.
+ */
+export async function runPublish(
+  targetPath: string,
+  deps: PublishDeps,
+): Promise<PublishResult> {
+  // 1. Logged-in gate — refuse BEFORE any packing/upload.
+  const idToken = deps.loadIdToken();
+  if (!idToken) {
+    throw new Error('Not logged in — run `hq login` before publishing. Nothing was uploaded.');
+  }
+  const author = resolveAuthor(peekIdToken(idToken));
+
+  // Resolve a payload dir. We stamp/validate against a temp copy so we never
+  // mutate the user's working tree's package.yaml.
+  const absTarget = path.resolve(process.cwd(), targetPath);
+  if (!fs.existsSync(absTarget) || !fs.statSync(absTarget).isDirectory()) {
+    throw new Error(`Not a directory: ${absTarget}`);
+  }
+  const workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hq-publish-'));
+  const payloadDir = path.join(workDir, 'payload');
+  try {
+    fs.cpSync(absTarget, payloadDir, { recursive: true });
+
+    // 2. Stamp author (AC1) BEFORE validation so the stamped author is what
+    //    gets validated, packed, and recorded.
+    if (!fs.existsSync(path.join(payloadDir, 'package.yaml'))) {
+      throw new Error(`package.yaml missing from ${absTarget} — nothing was uploaded.`);
+    }
+    stampAuthorIntoPackage(payloadDir, author);
+
+    // 3. Validate with the canonical 10-rule validator. Throws on any failure;
+    //    we have uploaded nothing at this point.
+    const pkg = validateManifest(payloadDir, deps.hqVersion);
+
+    // 4. Tar + base64 + authenticated JSON upload. The deployed server
+    //    JSON.parses the body, so we send the gzip tarball base64-encoded
+    //    inside a JSON listing request (NOT a raw octet-stream body).
+    const tarballBytes = tarballPayload(payloadDir);
+    const token = await deps.getAccessToken();
+    const listing: ListingRequest = {
+      type: inferListingType(pkg),
+      name: pkg.name,
+      slug: deriveSlug(pkg.name),
+      version: pkg.version,
+      summary: pkg.description,
+      contributes: summarizeContributes(pkg.contributes) || undefined,
+      // Server prefers the caller's claimed creator handle, but we stamp our
+      // resolved handle as a backwards-compat fallback.
+      creatorHandle: author.handle,
+      tarball: Buffer.from(tarballBytes).toString('base64'),
+    };
+    const { status, body } = await deps.upload({ token, listing });
+    const notice = buildListingNotice(status, body, pkg.name, pkg.version);
+    // Unwrap the `{ listing }` success envelope the server sends so attribution
+    // reads the server's resolved handle (fall back to top-level for compat).
+    const serverHandle = unwrapListing(body).creatorHandle?.trim();
+
+    // 5. Provenance (only after a successful upload).
+    recordProvenance(deps.hqRoot, pkg, absTarget);
+
+    return { notice, author, pkg, serverAttributed: Boolean(serverHandle) };
+  } finally {
+    fs.rmSync(workDir, { recursive: true, force: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Command wiring
+// ---------------------------------------------------------------------------
+
+function readHqVersion(hqRoot: string): string | null {
+  const p = path.join(hqRoot, 'core.yaml');
+  if (!fs.existsSync(p)) return null;
+  try {
+    const c = yaml.load(fs.readFileSync(p, 'utf-8')) as { hqVersion?: string };
+    return c?.hqVersion ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function registerPublishCommand(program: Command): void {
+  program
+    .command('publish <path>')
+    .description(
+      'Package a skill/worker pack and submit it to the HQ marketplace (POST /v1/listings).',
+    )
+    .action(async (targetPath: string) => {
+      try {
+        const hqRoot = findHqRoot();
+        const result = await runPublish(targetPath, {
+          loadIdToken: () => {
+            const cached = loadCachedTokens();
+            if (!cached || isExpiring(cached, 0)) return null;
+            return cached.idToken;
+          },
+          getAccessToken: () => ensureCognitoToken({ interactive: false }),
+          upload: async ({ token, listing }) => {
+            // JSON body (application/json) — the deployed handler JSON.parses
+            // the body and base64-decodes `listing.tarball`. vaultApiFetch
+            // sends application/json + the bearer token.
+            const res = await vaultApiFetch({
+              token,
+              path: '/v1/listings',
+              method: 'POST',
+              body: listing as unknown as Record<string, unknown>,
+            });
+            const json = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+            return { status: res.status, body: json };
+          },
+          hqRoot,
+          hqVersion: readHqVersion(hqRoot),
+        });
+        console.log(chalk.green(result.notice));
+        // Only print the locally-resolved author as a fallback when the server
+        // did NOT return its own resolved handle (already in the notice).
+        if (!result.serverAttributed) {
+          console.log(
+            chalk.dim(
+              `  Attributed to ${result.author.displayName} (@${result.author.handle}).`,
+            ),
+          );
+        }
+      } catch (err) {
+        console.error(
+          chalk.red('Error:'),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+}