@indigoai-us/hq-cli 5.77.13 → 5.78.0

package/src/commands/publish.ts

@@ -1,580 +0,0 @@
-/**
- * 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 { parseUserYaml } from '../utils/user-yaml-error.js';
-import { execFileSync } from 'child_process';
-import { Command } from 'commander';
-import chalk from 'chalk';
-import { loadCachedTokens, isExpiring } from '@indigoai-us/hq-cloud';
-import { ensureCognitoToken, ensureCognitoIdToken } 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 { readHqVersion } from '../utils/pack-contributions.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 = parseUserYaml<Record<string, unknown>>(
-    fs.readFileSync(manifestPath, 'utf-8'),
-    manifestPath,
-  );
-  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 === 400) {
-    const code = typeof body.code === 'string' ? body.code : '';
-    if (code === 'ON_BEHALF_DISABLED') {
-      throw new Error(
-        'Publishing on behalf of another creator is not enabled on this server. ' +
-          'Ask an HQ admin to turn on the on-behalf capability, or publish without `--as`.',
-      );
-    }
-    // Any other 400 falls through to the generic non-2xx handler below.
-  }
-  if (status === 401 || status === 403) {
-    const code = typeof body.code === 'string' ? body.code : '';
-    if (code === 'NOT_VERIFIED_CREATOR') {
-      throw new Error(
-        'Only verified creators can publish to the marketplace. ' +
-          'Run `hq creators apply --reason "..."` to request verified-creator access; ' +
-          'an Indigo admin will review it.',
-      );
-    }
-    if (code === 'FORBIDDEN' || code === 'NO_EMAIL_CLAIM') {
-      // The staff gate rejected an on-behalf (`--as`) publish — only the normal
-      // self-publish path returns NOT_VERIFIED_CREATOR, so these codes here mean
-      // a non-staff caller tried to publish as someone else.
-      throw new Error(
-        'Only HQ staff can publish on behalf of another creator (`--as`). ' +
-          'Re-run without `--as` to publish as yourself.',
-      );
-    }
-    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;
-  /**
-   * OPTIONAL staff-gated publish-on-behalf target handle (`hq publish --as
-   * <handle>`). When set, the server attributes the listing to the seeded,
-   * UNCLAIMED creator with this handle instead of the caller — but only if the
-   * caller is staff (`@getindigo.ai`) and the server has the capability enabled.
-   */
-  publishAsHandle?: 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 (normal self-publish). */
-  getAccessToken: () => Promise<string>;
-  /**
-   * Returns a non-interactive ID token. Required for an on-behalf publish
-   * (`--as <handle>`): the server's staff gate reads the `email` claim, which is
-   * on the id_token only — the access token returns 403 NO_EMAIL_CLAIM.
-   */
-  getIdToken: () => 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,
-  opts: { publishAsHandle?: string } = {},
-): 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));
-  const publishAsHandle =
-    typeof opts.publishAsHandle === 'string' && opts.publishAsHandle.length > 0
-      ? opts.publishAsHandle
-      : undefined;
-
-  // 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.`);
-    }
-    // On the on-behalf path (`--as <handle>`) the SERVER is authoritative for
-    // attribution (it resolves the target creator by handle and ignores the
-    // manifest/stamped author), so we must NOT overwrite the manifest's author
-    // with the CALLER's identity — the manifest already names the target
-    // creator. Stamp the caller only on the normal self-publish path.
-    if (!publishAsHandle) {
-      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);
-    // On-behalf publishes are staff-gated server-side and the staff gate reads
-    // the id_token `email` claim — send the ID token, not the access token
-    // (which has no email and would 403 NO_EMAIL_CLAIM). Normal self-publish
-    // continues to use the access token.
-    const token = publishAsHandle
-      ? await deps.getIdToken()
-      : 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,
-      // On-behalf: send the target handle so the body is self-describing (the
-      // server is authoritative for attribution either way). Normal: our
-      // resolved handle is a backwards-compat fallback under the server's
-      // claimed-handle lookup.
-      creatorHandle: publishAsHandle ?? author.handle,
-      ...(publishAsHandle ? { publishAsHandle } : {}),
-      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
-// ---------------------------------------------------------------------------
-
-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).',
-    )
-    .option(
-      '--as <handle>',
-      'Publish on behalf of a seeded, unclaimed creator by handle (HQ staff only). ' +
-        'The listing is attributed to that creator instead of you.',
-    )
-    .option('--on-behalf <handle>', 'Alias for --as.')
-    .action(async (targetPath: string, options: { as?: string; onBehalf?: string }) => {
-      try {
-        const publishAsHandle = options.as ?? options.onBehalf;
-        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 }),
-          getIdToken: () => ensureCognitoIdToken({ 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),
-        }, { publishAsHandle });
-        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);
-      }
-    });
-}