fix: merge forking operations in bucket commands (#38)

Author: designcode

src/cli-core.ts

@@ -4,6 +4,7 @@
 
 import { Command as CommanderCommand } from 'commander';
 import type { Argument, CommandSpec, Specs } from './types.js';
+import { printDeprecated } from './utils/messages.js';
 
 export interface ModuleLoader {
   (commandPath: string[]): Promise<{
@@ -448,6 +449,10 @@ export function registerCommands(
               return;
             }
 
+            if (defaultCmd.deprecated && defaultCmd.messages?.onDeprecated) {
+              printDeprecated(defaultCmd.messages.onDeprecated);
+            }
+
             await loadAndExecuteCommand(
               loadModule,
               [...currentPath, defaultCmd.name],
@@ -479,6 +484,10 @@ export function registerCommands(
           return;
         }
 
+        if (spec.deprecated && spec.messages?.onDeprecated) {
+          printDeprecated(spec.messages.onDeprecated);
+        }
+
         await loadAndExecuteCommand(
           loadModule,
           currentPath,

src/lib/buckets/create.ts

@@ -31,6 +31,12 @@ export default async function create(options: Record<string, unknown>) {
   ]);
   let defaultTier = getOption<string>(options, ['default-tier', 't', 'T']);
   let locations = getOption<string>(options, ['locations', 'l', 'L']);
+  const forkOf = getOption<string>(options, ['fork-of', 'forkOf', 'fork']);
+  const sourceSnapshot = getOption<string>(options, [
+    'source-snapshot',
+    'sourceSnapshot',
+    'source-snap',
+  ]);
 
   // Handle deprecated --region and --consistency options
   const deprecatedRegion = getOption<string>(options, ['region', 'r', 'R']);
@@ -125,11 +131,18 @@ export default async function create(options: Record<string, unknown>) {
     process.exit(1);
   }
 
+  if (sourceSnapshot && !forkOf) {
+    printFailure(context, '--source-snapshot requires --fork-of');
+    process.exit(1);
+  }
+
   const { error } = await createBucket(name, {
     defaultTier: (defaultTier ?? 'STANDARD') as StorageClass,
     enableSnapshot: enableSnapshots === true,
     access: (access ?? 'private') as 'public' | 'private',
     locations: parsedLocations ?? parseLocations(locations ?? 'global'),
+    ...(forkOf ? { sourceBucketName: forkOf } : {}),
+    ...(sourceSnapshot ? { sourceBucketSnapshot: sourceSnapshot } : {}),
     config: await getStorageConfig(),
   });
 

src/lib/buckets/list.ts

@@ -1,7 +1,7 @@
 import { getOption } from '../../utils/options.js';
 import { formatOutput } from '../../utils/format.js';
 import { getStorageConfig } from '../../auth/s3-client.js';
-import { listBuckets } from '@tigrisdata/storage';
+import { listBuckets, getBucketInfo } from '@tigrisdata/storage';
 import {
   printStart,
   printSuccess,
@@ -17,10 +17,10 @@ export default async function list(options: Record<string, unknown>) {
 
   try {
     const format = getOption<string>(options, ['format', 'F'], 'table');
+    const forksOf = getOption<string>(options, ['forks-of', 'forksOf']);
+    const config = await getStorageConfig();
 
-    const { data, error } = await listBuckets({
-      config: await getStorageConfig(),
-    });
+    const { data, error } = await listBuckets({ config });
 
     if (error) {
       printFailure(context, error.message);
@@ -32,6 +32,48 @@ export default async function list(options: Record<string, unknown>) {
       return;
     }
 
+    if (forksOf) {
+      // Filter for forks of the named source bucket
+      const { data: bucketInfo, error: infoError } = await getBucketInfo(
+        forksOf,
+        { config }
+      );
+
+      if (infoError) {
+        printFailure(context, infoError.message);
+        process.exit(1);
+      }
+
+      if (!bucketInfo.hasForks) {
+        printEmpty(context);
+        return;
+      }
+
+      const forks: Array<{ name: string; created: Date }> = [];
+
+      for (const bucket of data.buckets) {
+        if (bucket.name === forksOf) continue;
+        const { data: info } = await getBucketInfo(bucket.name, { config });
+        if (info?.sourceBucketName === forksOf) {
+          forks.push({ name: bucket.name, created: bucket.creationDate });
+        }
+      }
+
+      if (forks.length === 0) {
+        printEmpty(context);
+        return;
+      }
+
+      const output = formatOutput(forks, format!, 'forks', 'fork', [
+        { key: 'name', header: 'Name' },
+        { key: 'created', header: 'Created' },
+      ]);
+
+      console.log(output);
+      printSuccess(context, { count: forks.length });
+      return;
+    }
+
     const buckets = data.buckets.map((bucket) => ({
       name: bucket.name,
       created: bucket.creationDate,

src/lib/mk.ts

@@ -40,6 +40,12 @@ export default async function mk(options: Record<string, unknown>) {
       'T',
     ]);
     let locations = getOption<string>(options, ['locations', 'l', 'L']);
+    const forkOf = getOption<string>(options, ['fork-of', 'forkOf', 'fork']);
+    const sourceSnapshot = getOption<string>(options, [
+      'source-snapshot',
+      'sourceSnapshot',
+      'source-snap',
+    ]);
 
     // Handle deprecated --region and --consistency options
     const deprecatedRegion = getOption<string>(options, ['region', 'r', 'R']);
@@ -62,11 +68,18 @@ export default async function mk(options: Record<string, unknown>) {
       );
     }
 
+    if (sourceSnapshot && !forkOf) {
+      console.error('--source-snapshot requires --fork-of');
+      process.exit(1);
+    }
+
     const { error } = await createBucket(bucket, {
       defaultTier: (defaultTier ?? 'STANDARD') as StorageClass,
       enableSnapshot: enableSnapshots === true,
       access: (access ?? 'private') as 'public' | 'private',
       locations: parseLocations(locations ?? 'global'),
+      ...(forkOf ? { sourceBucketName: forkOf } : {}),
+      ...(sourceSnapshot ? { sourceBucketSnapshot: sourceSnapshot } : {}),
       config,
     });
 

src/specs.yaml

@@ -262,6 +262,8 @@ commands:
       - "tigris mk my-bucket --access public --region iad"
       - "tigris mk my-bucket/images/"
       - "tigris mk t3://my-bucket"
+      - "tigris mk my-fork --fork-of my-bucket"
+      - "tigris mk my-fork --fork-of my-bucket --source-snapshot 1765889000501544464"
     messages:
       onFailure: 'Failed to create. Check the name is valid and your credentials have write access'
     arguments:
@@ -307,6 +309,12 @@ commands:
         alias: l
         options: *location_options
         default: 'global'
+      - name: fork-of
+        description: Create this bucket as a fork (copy-on-write clone) of the named source bucket
+        alias: fork
+      - name: source-snapshot
+        description: Fork from a specific snapshot of the source bucket. Accepts a snapshot version string or any UNIX nanosecond-precision timestamp (e.g. 1765889000501544464). Requires --fork-of
+        alias: source-snap
 
   # touch
   - name: touch
@@ -578,6 +586,7 @@ commands:
         examples:
           - "tigris buckets list"
           - "tigris buckets list --format json"
+          - "tigris buckets list --forks-of my-bucket"
         messages:
           onStart: 'Listing buckets...'
           onSuccess: 'Found {{count}} bucket(s)'
@@ -589,6 +598,8 @@ commands:
             alias: f
             options: [json, table, xml]
             default: table
+          - name: forks-of
+            description: Only list buckets that are forks of the named source bucket
       # create
       - name: create
         description: Create a new bucket with optional access, tier, and location settings
@@ -597,6 +608,8 @@ commands:
           - "tigris buckets create my-bucket"
           - "tigris buckets create my-bucket --access public --locations iad"
           - "tigris buckets create my-bucket --enable-snapshots --default-tier STANDARD_IA"
+          - "tigris buckets create my-fork --fork-of my-bucket"
+          - "tigris buckets create my-fork --fork-of my-bucket --source-snapshot 1765889000501544464"
         messages:
           onStart: 'Creating bucket...'
           onSuccess: "Bucket '{{name}}' created successfully"
@@ -641,6 +654,12 @@ commands:
             alias: l
             options: *location_options
             default: 'global'
+          - name: fork-of
+            description: Create this bucket as a fork (copy-on-write clone) of the named source bucket
+            alias: fork
+          - name: source-snapshot
+            description: Fork from a specific snapshot of the source bucket. Accepts a snapshot version string or any UNIX nanosecond-precision timestamp (e.g. 1765889000501544464). Requires --fork-of
+            alias: source-snap
       # get
       - name: get
         description: Show details for a bucket including access level, region, tier, and custom domain
@@ -935,15 +954,16 @@ commands:
   # Manage forks
   #########################
   - name: forks
-    description: List and create forks. A fork is a writable copy-on-write clone of a bucket, useful for testing or branching data
+    description: (Deprecated, use "buckets create --fork-of" and "buckets list --forks-of") List and create forks
     alias: f
     examples:
       - "tigris forks list my-bucket"
       - "tigris forks create my-bucket my-fork"
     commands:
       # list
       - name: list
-        description: List all forks created from the given source bucket
+        description: (Deprecated, use "buckets list --forks-of") List all forks created from the given source bucket
+        deprecated: true
         alias: l
         examples:
           - "tigris forks list my-bucket"
@@ -953,6 +973,7 @@ commands:
           onSuccess: 'Found {{count}} fork(s)'
           onFailure: 'Failed to list forks'
           onEmpty: 'No forks found for this bucket'
+          onDeprecated: 'Use "tigris buckets list --forks-of <bucket>" instead'
         arguments:
           - name: name
             description: Name of the source bucket
@@ -967,15 +988,17 @@ commands:
             default: table
       # create
       - name: create
-        description: Create a new fork (copy-on-write clone) of the source bucket. Optionally fork from a specific snapshot
+        description: (Deprecated, use "buckets create --fork-of") Create a new fork (copy-on-write clone) of the source bucket
+        deprecated: true
         alias: c
         examples:
           - "tigris forks create my-bucket my-fork"
-          - "tigris forks create my-bucket my-fork --snapshot snap-2025-01-01"
+          - "tigris forks create my-bucket my-fork --snapshot 1765889000501544464"
         messages:
           onStart: 'Creating fork...'
           onSuccess: "Fork '{{forkName}}' created from '{{name}}'"
           onFailure: 'Failed to create fork'
+          onDeprecated: 'Use "tigris buckets create <name> --fork-of <bucket>" instead'
         arguments:
           - name: name
             description: Name of the source bucket
@@ -990,7 +1013,7 @@ commands:
             examples:
               - my-fork
           - name: snapshot
-            description: Create fork from a specific snapshot
+            description: Create fork from a specific snapshot. Accepts a snapshot version string or any UNIX nanosecond-precision timestamp (e.g. 1765889000501544464)
             alias: s
 
   #########################

src/types.ts

@@ -19,6 +19,7 @@ export interface Messages {
   onFailure?: string;
   onEmpty?: string;
   onAlreadyDone?: string;
+  onDeprecated?: string;
   hint?: string;
 }
 
@@ -31,6 +32,7 @@ export interface CommandSpec {
   examples?: string[];
   commands?: CommandSpec[]; // recursive - can nest infinitely
   default?: string;
+  deprecated?: boolean;
   message?: string;
   messages?: Messages;
 }

src/utils/messages.ts

@@ -150,6 +150,15 @@ export function printHint(
   }
 }
 
+/**
+ * Print a deprecation warning for a command
+ * Suppressed when output is piped/redirected
+ */
+export function printDeprecated(message: string): void {
+  if (!isTTY()) return;
+  console.warn(`⚠ Deprecated: ${message}`);
+}
+
 /**
  * Helper to create a message context
  */