@aaronshaf/confluence-cli 0.1.15 → 1.0.0

package/README.md

@@ -34,7 +34,6 @@ Credentials are stored in `~/.cn/config.json`. Space configuration is saved to `
 | `cn setup` | Configure Confluence credentials |
 | `cn clone <SPACE_KEY>` | Clone a space to a new folder |
 | `cn pull` | Pull changes from Confluence as markdown |
-| `cn push [file]` | Push local markdown file(s) to Confluence |
 | `cn status` | Check connection and sync status |
 | `cn tree` | Display page hierarchy |
 | `cn open [page]` | Open page in browser |
@@ -48,6 +47,7 @@ Credentials are stored in `~/.cn/config.json`. Space configuration is saved to `
 | `cn labels <id\|file>` | Manage page labels |
 | `cn move <id\|file> <parentId>` | Move a page to a new parent |
 | `cn attachments <id\|file>` | Manage page attachments |
+| `cn folder <subcommand>` | Manage folders (create, list, delete, move) |
 
 Run `cn <command> --help` for details on each command.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aaronshaf/confluence-cli",
-  "version": "0.1.15",
+  "version": "1.0.0",
   "description": "Confluence CLI for syncing spaces and local markdown files",
   "type": "module",
   "bin": {

package/src/cli/commands/folder.ts

@@ -0,0 +1,189 @@
+import { confirm } from '@inquirer/prompts';
+import chalk from 'chalk';
+import { ConfluenceClient } from '../../lib/confluence-client/index.js';
+import { ConfigManager } from '../../lib/config.js';
+import { EXIT_CODES } from '../../lib/errors.js';
+import { escapeXml } from '../../lib/formatters.js';
+import { readSpaceConfig } from '../../lib/space-config.js';
+
+/**
+ * Extract a flag value from an args array, e.g. --space DOCS -> "DOCS"
+ */
+function getFlagValue(args: string[], flag: string): string | undefined {
+  const idx = args.indexOf(flag);
+  if (idx !== -1 && idx + 1 < args.length && !args[idx + 1].startsWith('--')) {
+    return args[idx + 1];
+  }
+  return undefined;
+}
+
+/**
+ * Get positional args by stripping flags and their values
+ */
+function getPositionals(args: string[], flagsWithValues: string[]): string[] {
+  const result: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith('--')) {
+      if (flagsWithValues.includes(args[i])) {
+        i++; // skip the value too
+      }
+    } else {
+      result.push(args[i]);
+    }
+  }
+  return result;
+}
+
+export async function folderCommand(subcommand: string, subArgs: string[], allArgs: string[]): Promise<void> {
+  const configManager = new ConfigManager();
+  const config = await configManager.getConfig();
+
+  if (!config) {
+    console.error(chalk.red('Not configured. Run: cn setup'));
+    process.exit(EXIT_CODES.CONFIG_ERROR);
+  }
+
+  const client = new ConfluenceClient(config);
+
+  switch (subcommand) {
+    case 'create': {
+      const positionals = getPositionals(subArgs, ['--space', '--parent']);
+      const title = positionals[0];
+      if (!title) {
+        console.error(chalk.red('Folder title is required.'));
+        console.log(chalk.gray('Usage: cn folder create <title> --space <key>'));
+        process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+      }
+
+      const spaceKeyArg = getFlagValue(allArgs, '--space');
+      const parentId = getFlagValue(allArgs, '--parent');
+
+      let spaceId: string;
+
+      if (spaceKeyArg) {
+        const space = await client.getSpaceByKey(spaceKeyArg);
+        spaceId = space.id;
+      } else {
+        const spaceConfig = readSpaceConfig(process.cwd());
+        if (!spaceConfig) {
+          console.error(chalk.red('Not in a cloned space directory. Use --space to specify a space key.'));
+          process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+        }
+        spaceId = spaceConfig.spaceId;
+      }
+
+      const folder = await client.createFolder({ spaceId, title, parentId });
+      console.log(`${chalk.green('Created:')} "${folder.title}" (${folder.id})`);
+      break;
+    }
+
+    case 'list': {
+      const spaceKeyArg = getFlagValue(allArgs, '--space');
+
+      let spaceKey: string;
+
+      if (spaceKeyArg) {
+        spaceKey = spaceKeyArg;
+      } else {
+        const spaceConfig = readSpaceConfig(process.cwd());
+        if (!spaceConfig) {
+          console.error(chalk.red('Not in a cloned space directory. Use --space to specify a space key.'));
+          process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+        }
+        spaceKey = spaceConfig.spaceKey;
+      }
+
+      const cql = `type=folder AND space="${spaceKey.replace(/"/g, '\\"')}"`;
+      const PAGE_SIZE = 100;
+      const allResults: (typeof firstPage.results)[number][] = [];
+      let start = 0;
+
+      const firstPage = await client.search(cql, PAGE_SIZE, start);
+      allResults.push(...firstPage.results);
+      const total = firstPage.totalSize ?? firstPage.results.length;
+
+      while (allResults.length < total) {
+        start += PAGE_SIZE;
+        const page = await client.search(cql, PAGE_SIZE, start);
+        if (page.results.length === 0) break;
+        allResults.push(...page.results);
+      }
+
+      const xml = allArgs.includes('--xml');
+
+      if (xml) {
+        console.log('<folders>');
+        for (const result of allResults) {
+          const c = result.content;
+          if (c) {
+            console.log(`  <folder>`);
+            console.log(`    <id>${escapeXml(c.id ?? '')}</id>`);
+            console.log(`    <title>${escapeXml(c.title ?? '')}</title>`);
+            console.log(`  </folder>`);
+          }
+        }
+        console.log('</folders>');
+      } else {
+        if (allResults.length === 0) {
+          console.log(chalk.gray('No folders found.'));
+        } else {
+          for (const result of allResults) {
+            const c = result.content;
+            if (c) {
+              console.log(`${chalk.cyan(c.id)}  ${c.title}`);
+            }
+          }
+        }
+      }
+      break;
+    }
+
+    case 'delete': {
+      const positionals = getPositionals(subArgs, []);
+      const folderId = positionals[0];
+      if (!folderId) {
+        console.error(chalk.red('Folder ID is required.'));
+        console.log(chalk.gray('Usage: cn folder delete <id>'));
+        process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+      }
+
+      if (!allArgs.includes('--force')) {
+        const folder = await client.getFolder(folderId);
+        const confirmed = await confirm({
+          message: `Delete folder "${folder.title}" (${folderId})?`,
+          default: false,
+        });
+        if (!confirmed) {
+          console.log('Cancelled.');
+          return;
+        }
+      }
+
+      await client.deleteFolder(folderId);
+      console.log(`${chalk.green('Deleted:')} ${folderId}`);
+      break;
+    }
+
+    case 'move': {
+      const positionals = getPositionals(subArgs, []);
+      if (positionals.length < 2) {
+        console.error(chalk.red('Folder ID and parent ID are required.'));
+        console.log(chalk.gray('Usage: cn folder move <id> <parentId>'));
+        process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+      }
+
+      const folderId = positionals[0] as string;
+      const parentId = positionals[1] as string;
+      const [folder, parent] = await Promise.all([client.getFolder(folderId), client.getFolder(parentId)]);
+
+      await client.movePage(folderId, parentId);
+      console.log(`${chalk.green('Moved:')} "${folder.title}" under "${parent.title}"`);
+      break;
+    }
+
+    default:
+      console.error(chalk.red(`Unknown folder subcommand: ${subcommand}`));
+      console.log(chalk.gray('Run "cn folder --help" for usage information.'));
+      process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+  }
+}

package/src/cli/help.ts

@@ -89,41 +89,6 @@ ${chalk.yellow('Examples:')}
 `);
 }
 
-export function showPushHelp(): void {
-  console.log(`
-${chalk.bold('cn push - Push local markdown files to Confluence')}
-
-${chalk.yellow('Usage:')}
-  cn push [file] [options]
-
-${chalk.yellow('Description:')}
-  Push local markdown files to Confluence.
-
-  With a file argument: pushes that single file.
-  Without arguments: scans for changed files and prompts y/n for each.
-
-${chalk.yellow('Arguments:')}
-  file                      Path to markdown file (optional)
-
-${chalk.yellow('Options:')}
-  --force                   Ignore version conflicts and overwrite
-  --dry-run                 Preview changes without pushing
-  --help                    Show this help message
-
-${chalk.yellow('Examples:')}
-  cn push                          Scan and prompt for all changed files
-  cn push --dry-run                Preview what would be pushed
-  cn push ./docs/page.md           Push single page
-  cn push ./docs/page.md --force   Force push (ignore version conflict)
-
-${chalk.yellow('Notes:')}
-  - New files (no page_id) will be created on Confluence
-  - Modified files are detected by comparing file mtime vs synced_at
-  - Only basic markdown elements are fully supported
-  - Files are automatically renamed to match page titles (except index.md/README.md)
-`);
-}
-
 export function showStatusHelp(): void {
   console.log(`
 ${chalk.bold('cn status - Check connection and sync status')}
@@ -316,6 +281,35 @@ ${chalk.yellow('Options:')}
 `);
 }
 
+export function showFolderHelp(): void {
+  console.log(`
+${chalk.bold('cn folder - Manage Confluence folders')}
+
+${chalk.yellow('Usage:')}
+  cn folder <subcommand> [options]
+
+${chalk.yellow('Subcommands:')}
+  create <title>            Create a new folder
+  list                      List folders in a space
+  delete <id>               Delete a folder
+  move <id> <parentId>      Move a folder to a new parent
+
+${chalk.yellow('Options:')}
+  --space <key>             Space key (required for create/list if not in cloned dir)
+  --parent <id>             Parent folder ID (for create)
+  --force                   Skip confirmation prompt (for delete)
+  --xml                     Output in XML format (for list)
+  --help                    Show this help message
+
+${chalk.yellow('Examples:')}
+  cn folder create "My Folder" --space DOCS
+  cn folder create "Nested" --space DOCS --parent 123456
+  cn folder list --space DOCS
+  cn folder delete 123456
+  cn folder move 123456 789012
+`);
+}
+
 export function showMoveHelp(): void {
   console.log(`
 ${chalk.bold('cn move - Move a page to a new parent')}
@@ -386,7 +380,7 @@ ${chalk.yellow('Commands:')}
   cn setup                  Configure Confluence credentials
   cn clone                  Clone a space to a new folder
   cn pull                   Pull space to local folder
-  cn push                   Push local file to Confluence
+  cn folder                 Manage Confluence folders
   cn status                 Check connection and sync status
   cn tree                   Display page hierarchy
   cn open                   Open page in browser

package/src/cli/index.ts

@@ -16,8 +16,8 @@ import {
   showLabelsHelp,
   showMoveHelp,
   showOpenHelp,
+  showFolderHelp,
   showPullHelp,
-  showPushHelp,
   showSearchHelp,
   showSetupHelp,
   showSpacesHelp,
@@ -34,8 +34,8 @@ import { infoCommand } from './commands/info.js';
 import { labelsCommand } from './commands/labels.js';
 import { moveCommand } from './commands/move.js';
 import { openCommand } from './commands/open.js';
+import { folderCommand } from './commands/folder.js';
 import { pullCommand } from './commands/pull.js';
-import { pushCommand } from './commands/push.js';
 import { searchCommand } from './commands/search.js';
 import { setup } from './commands/setup.js';
 import { spacesCommand } from './commands/spaces.js';
@@ -128,20 +128,18 @@ async function main(): Promise<void> {
         break;
       }
 
-      case 'push': {
-        if (args.includes('--help')) {
-          showPushHelp();
+      case 'folder': {
+        if (args.includes('--help') && !subArgs.find((a) => !a.startsWith('--'))) {
+          showFolderHelp();
           process.exit(EXIT_CODES.SUCCESS);
         }
-
-        // File is optional - if not provided, scan for changes
-        const file = subArgs.find((arg) => !arg.startsWith('--'));
-
-        await pushCommand({
-          file,
-          force: args.includes('--force'),
-          dryRun: args.includes('--dry-run'),
-        });
+        const folderSubcommand = subArgs[0];
+        if (!folderSubcommand || folderSubcommand.startsWith('--')) {
+          showFolderHelp();
+          process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+        }
+        const folderSubArgs = subArgs.slice(1);
+        await folderCommand(folderSubcommand, folderSubArgs, args);
         break;
       }
 

package/src/lib/confluence-client/client.ts

@@ -12,6 +12,7 @@ import {
 } from '../errors.js';
 import {
   createFolderEffect as createFolderEffectFn,
+  deleteFolderEffect as deleteFolderEffectFn,
   findFolderByTitle as findFolderByTitleFn,
   getFolderEffect as getFolderEffectFn,
   movePageEffect as movePageEffectFn,
@@ -479,6 +480,20 @@ export class ConfluenceClient {
     return Effect.runPromise(this.createFolderEffect(request));
   }
 
+  /**
+   * Delete a folder by ID (Effect version)
+   */
+  deleteFolderEffect(
+    folderId: string,
+  ): Effect.Effect<void, ApiError | AuthError | NetworkError | RateLimitError | FolderNotFoundError> {
+    return deleteFolderEffectFn(this.baseUrl, this.authHeader, folderId);
+  }
+
+  /** Delete a folder by ID (async version) */
+  async deleteFolder(folderId: string): Promise<void> {
+    return Effect.runPromise(this.deleteFolderEffect(folderId));
+  }
+
   /**
    * Find a folder by title in a space
    * Uses v1 CQL search API to find folders by title
@@ -514,13 +529,14 @@ export class ConfluenceClient {
   searchEffect(
     cql: string,
     limit = 10,
+    start = 0,
   ): Effect.Effect<SearchResponse, ApiError | AuthError | NetworkError | RateLimitError> {
-    return searchEffectFn(this.baseUrl, this.authHeader, cql, limit);
+    return searchEffectFn(this.baseUrl, this.authHeader, cql, limit, start);
   }
 
   /** Search pages using CQL (async version) */
-  async search(cql: string, limit = 10): Promise<SearchResponse> {
-    return Effect.runPromise(this.searchEffect(cql, limit));
+  async search(cql: string, limit = 10, start = 0): Promise<SearchResponse> {
+    return Effect.runPromise(this.searchEffect(cql, limit, start));
   }
 
   // ================== Comments API ==================

package/src/lib/confluence-client/folder-operations.ts

@@ -118,6 +118,47 @@ export function createFolderEffect(
   );
 }
 
+/**
+ * Delete a folder by ID (Effect version)
+ */
+export function deleteFolderEffect(
+  baseUrl: string,
+  authHeader: string,
+  folderId: string,
+): Effect.Effect<void, ApiError | AuthError | NetworkError | RateLimitError | FolderNotFoundError> {
+  const makeRequest = Effect.tryPromise({
+    try: async () => {
+      const url = `${baseUrl}/wiki/api/v2/folders/${folderId}`;
+      const response = await fetch(url, {
+        method: 'DELETE',
+        headers: { Authorization: authHeader, Accept: 'application/json' },
+      });
+
+      if (response.status === 404) throw new FolderNotFoundError(folderId);
+      if (response.status === 401) throw new AuthError('Invalid credentials', 401);
+      if (response.status === 403) throw new AuthError('Access denied', 403);
+      if (response.status === 429) {
+        const retryAfter = response.headers.get('Retry-After');
+        throw new RateLimitError('Rate limited', retryAfter ? Number.parseInt(retryAfter, 10) : undefined);
+      }
+      if (!response.ok) throw new ApiError(`API error: ${response.status}`, response.status);
+    },
+    catch: (error) => {
+      if (
+        error instanceof FolderNotFoundError ||
+        error instanceof AuthError ||
+        error instanceof ApiError ||
+        error instanceof RateLimitError
+      ) {
+        return error;
+      }
+      return new NetworkError(`Network error: ${error}`);
+    },
+  });
+
+  return pipe(makeRequest, Effect.retry(rateLimitRetrySchedule));
+}
+
 /**
  * Move a page to a new parent (Effect version)
  * Uses v1 API: PUT /wiki/rest/api/content/{id}/move/{position}/{targetId}

package/src/lib/confluence-client/search-operations.ts

@@ -21,8 +21,9 @@ export function searchEffect(
   authHeader: string,
   cql: string,
   limit = 10,
+  start = 0,
 ): Effect.Effect<SearchResponse, ApiError | AuthError | NetworkError | RateLimitError> {
-  const url = `${baseUrl}/wiki/rest/api/search?cql=${encodeURIComponent(cql)}&limit=${limit}`;
+  const url = `${baseUrl}/wiki/rest/api/search?cql=${encodeURIComponent(cql)}&limit=${limit}&start=${start}`;
 
   const makeRequest = Effect.tryPromise({
     try: async () => {

package/src/test/folder-command.test.ts

@@ -0,0 +1,182 @@
+import { describe, expect, test } from 'bun:test';
+import { HttpResponse, http } from 'msw';
+import { ConfluenceClient } from '../lib/confluence-client/client.js';
+import { server } from './setup-msw.js';
+import { createValidFolder, createValidSpace } from './msw-schema-validation.js';
+
+const testConfig = {
+  confluenceUrl: 'https://test.atlassian.net',
+  email: 'test@example.com',
+  apiToken: 'test-token',
+};
+
+describe('cn folder - API layer', () => {
+  describe('createFolder', () => {
+    test('creates a folder with spaceId resolved from getSpaceByKey', async () => {
+      let capturedBody: unknown;
+
+      server.use(
+        http.get('*/wiki/api/v2/spaces', ({ request }) => {
+          const url = new URL(request.url);
+          const keys = url.searchParams.get('keys');
+          return HttpResponse.json({ results: [createValidSpace({ id: 'space-456', key: keys ?? 'DOCS' })] });
+        }),
+        http.post('*/wiki/api/v2/folders', async ({ request }) => {
+          capturedBody = await request.json();
+          return HttpResponse.json(createValidFolder({ id: 'folder-new', title: 'My Folder' }));
+        }),
+      );
+
+      const client = new ConfluenceClient(testConfig);
+      const space = await client.getSpaceByKey('DOCS');
+      const folder = await client.createFolder({ spaceId: space.id, title: 'My Folder' });
+
+      expect(space.id).toBe('space-456');
+      expect(folder.id).toBe('folder-new');
+      expect(folder.title).toBe('My Folder');
+      expect((capturedBody as { spaceId: string }).spaceId).toBe('space-456');
+    });
+
+    test('creates a folder with a parentId', async () => {
+      let capturedBody: unknown;
+
+      server.use(
+        http.post('*/wiki/api/v2/folders', async ({ request }) => {
+          capturedBody = await request.json();
+          return HttpResponse.json(
+            createValidFolder({ id: 'folder-child', title: 'Child Folder', parentId: 'folder-parent' }),
+          );
+        }),
+      );
+
+      const client = new ConfluenceClient(testConfig);
+      await client.createFolder({ spaceId: 'space-123', title: 'Child Folder', parentId: 'folder-parent' });
+
+      expect((capturedBody as { parentId: string }).parentId).toBe('folder-parent');
+    });
+  });
+
+  describe('deleteFolder', () => {
+    test('deletes a folder by ID', async () => {
+      let deletedId = '';
+
+      server.use(
+        http.delete('*/wiki/api/v2/folders/:folderId', ({ params }) => {
+          deletedId = params.folderId as string;
+          return new HttpResponse(null, { status: 204 });
+        }),
+      );
+
+      const client = new ConfluenceClient(testConfig);
+      await client.deleteFolder('folder-123');
+
+      expect(deletedId).toBe('folder-123');
+    });
+
+    test('throws FolderNotFoundError for 404', async () => {
+      server.use(
+        http.delete('*/wiki/api/v2/folders/:folderId', () => {
+          return HttpResponse.json({ message: 'Not found' }, { status: 404 });
+        }),
+      );
+
+      const client = new ConfluenceClient(testConfig);
+      await expect(client.deleteFolder('nonexistent')).rejects.toThrow();
+    });
+  });
+
+  describe('folder list pagination', () => {
+    test('fetches a single page when total fits in one request', async () => {
+      server.use(
+        http.get('*/wiki/rest/api/search', ({ request }) => {
+          const url = new URL(request.url);
+          const start = Number(url.searchParams.get('start') ?? 0);
+          if (start === 0) {
+            return HttpResponse.json({
+              results: [
+                { content: { id: 'f1', type: 'folder', title: 'Folder 1' } },
+                { content: { id: 'f2', type: 'folder', title: 'Folder 2' } },
+              ],
+              totalSize: 2,
+            });
+          }
+          return HttpResponse.json({ results: [], totalSize: 2 });
+        }),
+      );
+
+      const client = new ConfluenceClient(testConfig);
+      const page1 = await client.search('type=folder AND space="TEST"', 100, 0);
+      expect(page1.results).toHaveLength(2);
+      expect(page1.totalSize).toBe(2);
+    });
+
+    test('paginates when totalSize exceeds page size', async () => {
+      const allFolders = Array.from({ length: 150 }, (_, i) => ({
+        content: { id: `f${i}`, type: 'folder', title: `Folder ${i}` },
+      }));
+
+      server.use(
+        http.get('*/wiki/rest/api/search', ({ request }) => {
+          const url = new URL(request.url);
+          const start = Number(url.searchParams.get('start') ?? 0);
+          const limit = Number(url.searchParams.get('limit') ?? 10);
+          const slice = allFolders.slice(start, start + limit);
+          return HttpResponse.json({ results: slice, totalSize: 150 });
+        }),
+      );
+
+      const client = new ConfluenceClient(testConfig);
+      const collected = [];
+      let start = 0;
+      const PAGE_SIZE = 100;
+
+      const first = await client.search('type=folder AND space="TEST"', PAGE_SIZE, start);
+      collected.push(...first.results);
+      const total = first.totalSize ?? first.results.length;
+
+      while (collected.length < total) {
+        start += PAGE_SIZE;
+        const page = await client.search('type=folder AND space="TEST"', PAGE_SIZE, start);
+        if (page.results.length === 0) break;
+        collected.push(...page.results);
+      }
+
+      expect(collected).toHaveLength(150);
+    });
+  });
+
+  describe('getPositionals (arg parsing)', () => {
+    // Test the arg parsing logic directly via the folderCommand behavior
+    test('search passes start param in URL', async () => {
+      const capturedUrls: string[] = [];
+
+      server.use(
+        http.get('*/wiki/rest/api/search', ({ request }) => {
+          capturedUrls.push(request.url);
+          return HttpResponse.json({ results: [], totalSize: 0 });
+        }),
+      );
+
+      const client = new ConfluenceClient(testConfig);
+      await client.search('type=folder', 100, 42);
+
+      expect(capturedUrls[0]).toContain('start=42');
+    });
+
+    test('search passes limit param in URL', async () => {
+      const capturedUrls: string[] = [];
+
+      server.use(
+        http.get('*/wiki/rest/api/search', ({ request }) => {
+          capturedUrls.push(request.url);
+          return HttpResponse.json({ results: [], totalSize: 0 });
+        }),
+      );
+
+      const client = new ConfluenceClient(testConfig);
+      await client.search('type=folder', 50, 0);
+
+      expect(capturedUrls[0]).toContain('limit=50');
+    });
+  });
+});