@socialseal/cli 0.1.11 → 0.1.12

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 0.1.12 - 2026-06-23
+
+- Expose Asset Studio and video production tool surfaces through CLI discovery/schema output.
+- Add category-filtered tool discovery for users and agents.
+
 ## 0.1.11 - 2026-06-12
 
 - Add ad hoc public video URL analysis parity for queue and extract workflows, including `--url` and `--allow-untracked` support.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socialseal/cli",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "private": false,
   "type": "module",
   "description": "SocialSeal CLI (non-interactive)",

package/src/index.js

@@ -146,6 +146,94 @@ const KNOWN_TOOLS = [
     knownLocalDevState: 'enabled',
     notes: 'Accepts videoId/videoUid/platformVideoId/searchResultId items and public URL items with allowUntracked=true; videoId means video_uid or platform-native video id, not a tracking item id.',
   },
+  {
+    name: 'vnext-clips-read',
+    category: 'asset-studio',
+    description: 'List workspace clip-library items and optionally sign selected source videos.',
+    objectType: 'workspace_clip',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+  },
+  {
+    name: 'vnext-clips-create',
+    category: 'asset-studio',
+    description: 'Create signed clip upload targets and finalize uploaded clip metadata.',
+    objectType: 'workspace_clip',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    actionAliases: ['create', 'finalize'],
+    notes: 'The create action returns signed upload URLs; upload bytes to storage before calling finalize.',
+  },
+  {
+    name: 'vnext-clip-shot-mappings-read',
+    category: 'asset-studio',
+    description: 'Read clip-to-blueprint shot mappings for Asset Studio.',
+    objectType: 'clip_shot_mapping',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+  },
+  {
+    name: 'vnext-clip-shot-mappings-write',
+    category: 'asset-studio',
+    description: 'Upsert or delete clip-to-blueprint shot mappings for Asset Studio.',
+    objectType: 'clip_shot_mapping',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    actionAliases: ['upsert', 'delete'],
+  },
+  {
+    name: 'vnext-generated-assets-read',
+    category: 'asset-studio',
+    description: 'List generated rough cuts for a blueprint or read one generated asset.',
+    objectType: 'generated_asset',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    actionAliases: ['list', 'detail'],
+  },
+  {
+    name: 'vnext-generated-asset-create',
+    category: 'asset-studio',
+    description: 'Create a generated rough-cut asset from an edit spec.',
+    objectType: 'generated_asset',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+  },
+  {
+    name: 'vnext-generated-asset-optimize',
+    category: 'asset-studio',
+    description: 'Optimize a generated asset or create a new revision.',
+    objectType: 'generated_asset_revision',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+    actionAliases: ['optimize', 'create-revision'],
+  },
+  {
+    name: 'vnext-generated-asset-export',
+    category: 'asset-studio',
+    description: 'Export a generated rough cut as FCPXML.',
+    objectType: 'generated_asset_export',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+  },
+  {
+    name: 'vnext-generated-asset-share',
+    category: 'asset-studio',
+    description: 'Create, read, or revoke generated-asset share links.',
+    objectType: 'generated_asset_share',
+    transport: 'post_edge_function',
+    workspaceScoped: false,
+    knownLocalDevState: 'enabled',
+    actionAliases: ['create', 'read', 'revoke'],
+    notes: 'create/revoke require workspaceId in the body; read uses shareToken and does not require workspace scope.',
+  },
   { name: 'douyin-geo-api', category: 'search', description: 'Query Douyin search and geo data.' },
   {
     name: 'google-ai-search',
@@ -218,7 +306,34 @@ const KNOWN_TOOLS = [
   { name: 'vnext-blueprints-create', category: 'vnext', description: 'Create a vNext blueprint from grounded evidence.' },
   { name: 'vnext-blueprints-generate', category: 'vnext', description: 'Generate a vNext blueprint from workspace opportunity data.' },
   { name: 'vnext-blueprints-read', category: 'vnext', description: 'Read vNext blueprint history and specific versions.' },
+  {
+    name: 'vnext-blueprints-shots-read',
+    category: 'video-production',
+    description: 'Read shot-lift and pinned shot assets for a blueprint.',
+    objectType: 'blueprint_shot_asset',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+  },
+  {
+    name: 'vnext-blueprints-shots-refresh',
+    category: 'video-production',
+    description: 'Queue a refresh for blueprint shot assets.',
+    objectType: 'blueprint_shots_job',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+  },
   { name: 'vnext-briefs-create', category: 'vnext', description: 'Create a vNext brief record.' },
+  {
+    name: 'vnext-briefs-export',
+    category: 'video-production',
+    description: 'Export a generated vNext brief as markdown.',
+    objectType: 'vnext_brief_export',
+    transport: 'post_edge_function',
+    workspaceScoped: true,
+    knownLocalDevState: 'enabled',
+  },
   { name: 'vnext-briefs-generate', category: 'vnext', description: 'Generate a vNext brief from a blueprint or opportunity.' },
   { name: 'vnext-briefs-read', category: 'vnext', description: 'Read generated vNext briefs and version history.' },
   { name: 'vnext-intents', category: 'vnext', description: 'List, create, update, or delete vNext intents.' },
@@ -451,6 +566,311 @@ const TOOL_SCHEMA_HINTS = {
       'socialseal tools call --function tracked-video-extract --workspace-id <workspace-uuid> --body \'{"allowUntracked":true,"items":[{"url":"https://www.instagram.com/reel/SHORTCODE/"}]}\'',
     ],
   },
+  'vnext-clips-read': {
+    summary: 'List Asset Studio clip-library items and optionally sign selected video URLs.',
+    operations: [
+      {
+        action: 'list',
+        required: ['workspaceId or --workspace-id'],
+        optional: ['videoClipIds[] to include signed source video URLs'],
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          videoClipIds: ['11111111-1111-4111-8111-111111111111'],
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-clips-read --workspace-id <workspace-uuid> --body \'{"videoClipIds":["<clip-uuid>"]}\'',
+    ],
+  },
+  'vnext-clips-create': {
+    summary: 'Create signed upload targets for clips and finalize uploaded clip metadata.',
+    operations: [
+      {
+        action: 'create',
+        required: ['action=create', 'workspaceId or --workspace-id', 'fileName', 'mimeType'],
+        optional: [],
+        example: {
+          action: 'create',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          fileName: 'hero-shot.mp4',
+          mimeType: 'video/mp4',
+        },
+      },
+      {
+        action: 'finalize',
+        required: ['action=finalize', 'workspaceId or --workspace-id', 'clipId', 'fileName', 'storagePath', 'mimeType', 'sizeBytes', 'rightsAttested=true'],
+        optional: ['durationSeconds', 'width', 'height', 'posterPath'],
+        example: {
+          action: 'finalize',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          clipId: '11111111-1111-4111-8111-111111111111',
+          fileName: 'hero-shot.mp4',
+          storagePath: 'workspace-00000000-0000-4000-8000-000000000000/11111111-1111-4111-8111-111111111111.mp4',
+          mimeType: 'video/mp4',
+          sizeBytes: 1048576,
+          rightsAttested: true,
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-clips-create --workspace-id <workspace-uuid> --body \'{"action":"create","fileName":"hero-shot.mp4","mimeType":"video/mp4"}\'',
+      'socialseal tools call --function vnext-clips-create --workspace-id <workspace-uuid> --body @clip-finalize.json',
+    ],
+  },
+  'vnext-clip-shot-mappings-read': {
+    summary: 'Read Asset Studio clip-to-shot mappings for a blueprint.',
+    operations: [
+      {
+        action: 'read',
+        required: ['workspaceId or --workspace-id', 'blueprintId'],
+        optional: [],
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          blueprintId: '22222222-2222-4222-8222-222222222222',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-clip-shot-mappings-read --workspace-id <workspace-uuid> --body \'{"blueprintId":"<blueprint-uuid>"}\'',
+    ],
+  },
+  'vnext-clip-shot-mappings-write': {
+    summary: 'Upsert or delete Asset Studio clip-to-shot mappings.',
+    operations: [
+      {
+        action: 'upsert',
+        required: ['action=upsert', 'workspaceId or --workspace-id', 'blueprintId', 'panelId', 'clipId'],
+        optional: ['source (suggested|override)', 'score'],
+        example: {
+          action: 'upsert',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          blueprintId: '22222222-2222-4222-8222-222222222222',
+          panelId: 'panel-1',
+          clipId: '11111111-1111-4111-8111-111111111111',
+          source: 'override',
+        },
+      },
+      {
+        action: 'delete',
+        required: ['action=delete', 'workspaceId or --workspace-id', 'blueprintId', 'panelId'],
+        optional: [],
+        example: {
+          action: 'delete',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          blueprintId: '22222222-2222-4222-8222-222222222222',
+          panelId: 'panel-1',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-clip-shot-mappings-write --workspace-id <workspace-uuid> --body \'{"action":"upsert","blueprintId":"<blueprint-uuid>","panelId":"panel-1","clipId":"<clip-uuid>"}\'',
+    ],
+  },
+  'vnext-generated-assets-read': {
+    summary: 'List generated rough cuts for a blueprint or read one generated asset.',
+    operations: [
+      {
+        action: 'list',
+        required: ['action=list', 'workspaceId or --workspace-id', 'blueprintId'],
+        optional: [],
+        example: {
+          action: 'list',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          blueprintId: '22222222-2222-4222-8222-222222222222',
+        },
+      },
+      {
+        action: 'detail',
+        required: ['action=detail', 'workspaceId or --workspace-id', 'assetId'],
+        optional: [],
+        example: {
+          action: 'detail',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          assetId: '33333333-3333-4333-8333-333333333333',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-generated-assets-read --workspace-id <workspace-uuid> --body \'{"action":"list","blueprintId":"<blueprint-uuid>"}\'',
+      'socialseal tools call --function vnext-generated-assets-read --workspace-id <workspace-uuid> --body \'{"action":"detail","assetId":"<asset-uuid>"}\'',
+    ],
+  },
+  'vnext-generated-asset-create': {
+    summary: 'Create a generated rough cut from an Asset Studio edit spec.',
+    operations: [
+      {
+        action: 'create',
+        required: ['workspaceId or --workspace-id', 'blueprintId', 'title', 'editSpec'],
+        optional: [],
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          blueprintId: '22222222-2222-4222-8222-222222222222',
+          title: 'Homepage rough cut',
+          editSpec: {
+            version: 1,
+            fps: 30,
+            width: 1080,
+            height: 1920,
+            totalDurationSeconds: 3,
+            shots: [
+              {
+                panelId: 'panel-1',
+                clipId: '11111111-1111-4111-8111-111111111111',
+                title: 'Opening hook',
+                kind: 'hook',
+                shotLabel: 'Hero exterior',
+                sourceStartSeconds: 0,
+                durationSeconds: 3,
+                evidenceIds: [],
+              },
+            ],
+          },
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-generated-asset-create --workspace-id <workspace-uuid> --body @edit-spec.json',
+    ],
+  },
+  'vnext-generated-asset-optimize': {
+    summary: 'Optimize a generated asset or create a new revision.',
+    operations: [
+      {
+        action: 'optimize',
+        required: ['action=optimize', 'workspaceId or --workspace-id', 'assetId'],
+        optional: [],
+        example: {
+          action: 'optimize',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          assetId: '33333333-3333-4333-8333-333333333333',
+        },
+      },
+      {
+        action: 'create-revision',
+        required: ['action=create-revision', 'workspaceId or --workspace-id', 'assetId'],
+        optional: [],
+        example: {
+          action: 'create-revision',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          assetId: '33333333-3333-4333-8333-333333333333',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-generated-asset-optimize --workspace-id <workspace-uuid> --body \'{"action":"optimize","assetId":"<asset-uuid>"}\'',
+    ],
+  },
+  'vnext-generated-asset-export': {
+    summary: 'Export a generated rough cut as FCPXML.',
+    operations: [
+      {
+        action: 'export',
+        required: ['workspaceId or --workspace-id', 'assetId'],
+        optional: ['format=fcpxml'],
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          assetId: '33333333-3333-4333-8333-333333333333',
+          format: 'fcpxml',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-generated-asset-export --workspace-id <workspace-uuid> --body \'{"assetId":"<asset-uuid>","format":"fcpxml"}\'',
+    ],
+  },
+  'vnext-generated-asset-share': {
+    summary: 'Create, read, or revoke generated rough-cut share links.',
+    operations: [
+      {
+        action: 'create',
+        required: ['action=create', 'workspaceId', 'assetId'],
+        optional: ['ttlSeconds', 'shareBaseUrl'],
+        example: {
+          action: 'create',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          assetId: '33333333-3333-4333-8333-333333333333',
+          ttlSeconds: 604800,
+        },
+      },
+      {
+        action: 'read',
+        required: ['action=read', 'shareToken'],
+        optional: [],
+        example: {
+          action: 'read',
+          shareToken: '0123456789abcdef0123456789abcdef',
+        },
+      },
+      {
+        action: 'revoke',
+        required: ['action=revoke', 'workspaceId', 'shareLinkId'],
+        optional: [],
+        example: {
+          action: 'revoke',
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          shareLinkId: '44444444-4444-4444-8444-444444444444',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-generated-asset-share --body \'{"action":"create","workspaceId":"<workspace-uuid>","assetId":"<asset-uuid>"}\'',
+      'socialseal tools call --function vnext-generated-asset-share --body \'{"action":"read","shareToken":"<share-token>"}\'',
+    ],
+  },
+  'vnext-blueprints-shots-read': {
+    summary: 'Read blueprint shot-lift rows and pinned shot assets with signed URLs.',
+    operations: [
+      {
+        action: 'read',
+        required: ['workspaceId or --workspace-id', 'blueprintId'],
+        optional: ['signedUrlSeconds'],
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          blueprintId: '22222222-2222-4222-8222-222222222222',
+          signedUrlSeconds: 3600,
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-blueprints-shots-read --workspace-id <workspace-uuid> --body \'{"blueprintId":"<blueprint-uuid>"}\'',
+    ],
+  },
+  'vnext-blueprints-shots-refresh': {
+    summary: 'Queue a refresh for blueprint shot assets.',
+    operations: [
+      {
+        action: 'refresh',
+        required: ['workspaceId or --workspace-id', 'blueprintId'],
+        optional: [],
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          blueprintId: '22222222-2222-4222-8222-222222222222',
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-blueprints-shots-refresh --workspace-id <workspace-uuid> --body \'{"blueprintId":"<blueprint-uuid>"}\'',
+    ],
+  },
+  'vnext-briefs-export': {
+    summary: 'Export the latest or selected generated vNext brief as markdown.',
+    operations: [
+      {
+        action: 'export',
+        required: ['workspaceId or --workspace-id', 'opportunityKey'],
+        optional: ['version'],
+        example: {
+          workspaceId: '00000000-0000-4000-8000-000000000000',
+          opportunityKey: 'opportunity-key',
+          version: 1,
+        },
+      },
+    ],
+    cliExamples: [
+      'socialseal tools call --function vnext-briefs-export --workspace-id <workspace-uuid> --body \'{"opportunityKey":"<opportunity-key>"}\'',
+    ],
+  },
   'group-management': {
     summary: 'Manage single-platform tracking groups and memberships.',
     operations: [
@@ -544,6 +964,18 @@ function buildToolRegistry() {
   });
 }
 
+function filterToolRegistry(tools, category) {
+  const normalizedCategory = trimString(category).toLowerCase();
+  const filtered = normalizedCategory
+    ? tools.filter((tool) => trimString(tool.category).toLowerCase() === normalizedCategory)
+    : tools;
+  return [...filtered].sort((a, b) => {
+    const categoryCompare = trimString(a.category).localeCompare(trimString(b.category));
+    if (categoryCompare !== 0) return categoryCompare;
+    return trimString(a.name).localeCompare(trimString(b.name));
+  });
+}
+
 function getConfigPath() {
   return process.env.SOCIALSEAL_CONFIG || DEFAULT_CONFIG_PATH;
 }
@@ -1164,6 +1596,23 @@ function resolvePayloadWorkspaceId(payload, fallbackWorkspaceId) {
   return fallbackWorkspaceId || null;
 }
 
+function isGeneratedAssetShareScopedAction(functionName, payload) {
+  if (functionName !== 'vnext-generated-asset-share' || !isJsonObject(payload)) {
+    return false;
+  }
+  const action = trimString(payload.action).toLowerCase();
+  return action === 'create' || action === 'revoke';
+}
+
+function shouldRequireToolWorkspace(functionName, payload) {
+  const tool = getKnownTool(functionName);
+  const category = trimString(tool?.category).toLowerCase();
+  return (
+    Boolean(tool?.workspaceScoped) &&
+      (category === 'asset-studio' || category === 'video-production')
+  ) || isGeneratedAssetShareScopedAction(functionName, payload);
+}
+
 function isUuidLike(value) {
   return typeof value === 'string' && /^[0-9a-f]{8}-[0-9a-f-]{27}$/i.test(value.trim());
 }
@@ -3756,6 +4205,26 @@ async function handleToolsCall(opts) {
     });
   }
 
+  const scopedPayload = isJsonObject(translated.normalizedPayload)
+    ? translated.normalizedPayload
+    : (isJsonObject(translated.body) ? translated.body : payload);
+  const hasSpecialWorkspaceHandling = new Set([
+    'group-management',
+    'export_tracking_data',
+    'tracked-video-extract',
+  ]).has(opts.function);
+  if (!hasSpecialWorkspaceHandling && shouldRequireToolWorkspace(opts.function, scopedPayload)) {
+    requireWorkspaceSelection(effectiveWorkspaceId, {
+      label: opts.function,
+      hint: 'Pass --workspace-id, set SOCIALSEAL_WORKSPACE_ID, include workspaceId in the body, or configure a default workspace.',
+    });
+    emitWorkspaceSelectionNotice(opts, {
+      workspaceId: effectiveWorkspaceId,
+      source: effectiveWorkspaceSource,
+      label: opts.function,
+    });
+  }
+
   emitTrackingCreateScopeWarning(
     isJsonObject(translated.normalizedPayload) ? trimString(translated.normalizedPayload.action).toLowerCase() : '',
     effectiveWorkspaceId,
@@ -3854,9 +4323,10 @@ async function handleToolsCall(opts) {
 }
 
 function handleToolsList(opts) {
-  const tools = buildToolRegistry();
+  const tools = filterToolRegistry(buildToolRegistry(), opts.category);
   const payload = {
     discovery: 'built_in_registry',
+    category: trimString(opts.category) || null,
     tools,
     note: STATIC_TOOL_REGISTRY_NOTE,
     schemaNote: STATIC_TOOL_SCHEMA_NOTE,
@@ -3868,6 +4338,9 @@ function handleToolsList(opts) {
   }
 
   process.stdout.write('[socialseal] Built-in tool registry\n');
+  if (payload.category) {
+    process.stdout.write(`[socialseal] Category filter: ${payload.category}\n`);
+  }
   process.stdout.write(`[socialseal] ${payload.note}\n`);
   process.stdout.write(`[socialseal] ${payload.schemaNote}\n`);
 
@@ -4983,6 +5456,7 @@ const tools = program.command('tools').description('Call edge functions directly
 tools
   .command('list')
   .description('List built-in tool registry entries')
+  .option('--category <name>', 'Filter tools by category')
   .option('--json', 'Emit machine-readable output')
   .option('--pretty', 'Pretty-print JSON')
   .option('--verbose', 'Show error details')