atlasctl 0.1.0

package/README.md

@@ -0,0 +1,149 @@
+# atlasctl
+
+A Bun-based CLI for Atlassian workflows.
+
+Initial scope:
+- Fetch a Confluence page
+- Include all comments and nested replies
+- Include inline comment metadata when available
+
+## Requirements
+
+- Bun 1.3+
+
+## Install
+
+### Local development
+
+```bash
+bun install
+```
+
+Run directly:
+
+```bash
+bun run src/cli.ts --help
+```
+
+### Global (from npm)
+
+```bash
+npm install -g atlasctl
+```
+
+The CLI entrypoint uses Bun (`#!/usr/bin/env bun`), so Bun must be installed on the target machine.
+
+## Configuration
+
+Config file path:
+
+```text
+~/.atlasctl.json
+```
+
+Set required values:
+
+```bash
+atlasctl config set site your-domain.atlassian.net
+atlasctl config set email you@company.com
+atlasctl config set apikey <atlassian-api-token>
+```
+
+Or run guided setup for all required fields:
+
+```bash
+atlasctl config set
+```
+
+Guided setup requires an interactive terminal.
+
+Read values:
+
+```bash
+atlasctl config get site
+atlasctl config get email
+atlasctl config get apikey
+```
+
+Notes:
+- `apikey` is always redacted when read (`***hidden***`).
+- `config show` also redacts `apikey`.
+
+## Commands
+
+```text
+atlasctl config set
+atlasctl config set <site|email|apikey> <value>
+atlasctl config get <site|email|apikey>
+atlasctl config show
+atlasctl confluence page fetch <id-or-url> [--output <file>] [--pretty]
+atlasctl --help
+atlasctl --help-llm
+atlasctl --version
+```
+
+## Fetch a Confluence page
+
+By page ID:
+
+```bash
+atlasctl confluence page fetch 22982787097 --pretty
+```
+
+By URL:
+
+```bash
+atlasctl confluence page fetch "https://your-domain.atlassian.net/wiki/spaces/ENG/pages/22982787097/Page+Title"
+```
+
+Or write output to disk:
+
+```bash
+atlasctl confluence page fetch 22982787097 --output page.json --pretty
+```
+
+## URL and site matching
+
+When using a URL input, the URL host must match configured `site`.
+
+Example mismatch error:
+- URL host: `foo.atlassian.net`
+- Config site: `bar.atlassian.net`
+
+The command will fail fast to avoid calling the wrong tenant.
+
+## Output shape
+
+`confluence page fetch` returns JSON with:
+- `page`: core page metadata and body HTML
+- `comments`: tree of comments and replies
+- `meta`: fetch timestamp and total comment count
+
+Inline comments include:
+- `inlineContext.textSelection`
+- `inlineContext.markerRef`
+- `inlineContext.resolved`
+
+## Development
+
+Run tests:
+
+```bash
+bun test
+```
+
+Optional bundle build:
+
+```bash
+bun run build
+```
+
+## Publish to npm
+
+```bash
+bun test
+npm login
+npm publish --access public
+```
+
+If `atlasctl` is already taken on npm, switch to a scoped package name (for example `@your-scope/atlasctl`) while keeping the bin name as `atlasctl`.

package/bin/atlasctl

@@ -0,0 +1,9 @@
+#!/usr/bin/env bun
+
+import { run } from "../src/cli.ts";
+
+run().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "atlasctl",
+  "version": "0.1.0",
+  "description": "Atlassian CLI for Confluence page exports with comments",
+  "type": "module",
+  "packageManager": "bun@1.3.8",
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "bin": {
+    "atlasctl": "bin/atlasctl"
+  },
+  "scripts": {
+    "dev": "bun run src/cli.ts",
+    "build": "rm -rf dist && bun build src/cli.ts --target bun --outfile dist/cli.js",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "commander": "^14.0.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,215 @@
+#!/usr/bin/env bun
+
+import { writeFile } from "node:fs/promises";
+import { Command, InvalidArgumentError } from "commander";
+import {
+  CONFIG_KEYS,
+  type ConfigKey,
+  maskConfig,
+  normalizeConfigValue,
+  readConfig,
+  requireFetchConfig,
+  setConfigValue,
+  writeConfig,
+} from "./config";
+import { fetchConfluencePage } from "./confluence";
+import { getLlmHelpText } from "./llm-help";
+
+const VERSION = "0.1.0";
+
+function parseConfigKey(value: string): ConfigKey {
+  if (!CONFIG_KEYS.includes(value as ConfigKey)) {
+    throw new InvalidArgumentError(
+      `Invalid config key \"${value}\". Use one of: ${CONFIG_KEYS.join(", ")}`,
+    );
+  }
+
+  return value as ConfigKey;
+}
+
+async function handleConfigSet(key: ConfigKey, value: string): Promise<void> {
+  const configPath = await setConfigValue(key, value);
+  console.log(`Saved ${key} in ${configPath}`);
+}
+
+function configPromptLabel(key: ConfigKey): string {
+  if (key === "site") return "Atlassian site (for example: your-domain.atlassian.net)";
+  if (key === "email") return "Atlassian account email";
+  return "Atlassian API key";
+}
+
+function displayCurrentConfigValue(key: ConfigKey, value?: string): string {
+  if (!value) {
+    return "not set";
+  }
+
+  return key === "apikey" ? "***hidden***" : value;
+}
+
+async function handleConfigSetGuided(): Promise<void> {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error(
+      "Guided setup requires an interactive terminal. Use: atlasctl config set <site|email|apikey> <value>",
+    );
+  }
+
+  const config = await readConfig();
+  const updates: Partial<Record<ConfigKey, string>> = {};
+
+  for (const key of CONFIG_KEYS) {
+    while (true) {
+      const current = updates[key] ?? config[key];
+      const promptText = `${configPromptLabel(key)} [${displayCurrentConfigValue(key, current)}]: `;
+      const input = prompt(promptText)?.trim() ?? "";
+      const candidate = input || current;
+
+      if (!candidate) {
+        console.error(`${key} is required.`);
+        continue;
+      }
+
+      try {
+        updates[key] = normalizeConfigValue(key, candidate);
+        break;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+      }
+    }
+  }
+
+  const configPath = await writeConfig({
+    ...config,
+    ...updates,
+  });
+  console.log(`Saved site, email, apikey in ${configPath}`);
+}
+
+async function handleConfigGet(key: ConfigKey): Promise<void> {
+  const config = await readConfig();
+  const value = config[key];
+
+  if (!value) {
+    throw new Error(
+      `Config key \"${key}\" is not set. Use: atlasctl config set ${key} <value>`,
+    );
+  }
+
+  if (key === "apikey") {
+    console.log("***hidden***");
+    return;
+  }
+
+  console.log(value);
+}
+
+async function handleConfigShow(): Promise<void> {
+  const config = await readConfig();
+  console.log(JSON.stringify(maskConfig(config), null, 2));
+}
+
+async function handlePageFetch(
+  idOrUrl: string,
+  options: { output?: string; pretty?: boolean },
+): Promise<void> {
+  const config = requireFetchConfig(await readConfig());
+  const payload = await fetchConfluencePage(config, idOrUrl);
+
+  const pretty = options.pretty ?? false;
+  const json = pretty
+    ? `${JSON.stringify(payload, null, 2)}\n`
+    : `${JSON.stringify(payload)}\n`;
+
+  if (options.output) {
+    await writeFile(options.output, json, "utf8");
+    console.log(`Wrote ${payload.meta.totalComments} comments to ${options.output}`);
+    return;
+  }
+
+  process.stdout.write(json);
+}
+
+async function handleConfigSetCommand(key?: string, value?: string): Promise<void> {
+  if (!key && !value) {
+    await handleConfigSetGuided();
+    return;
+  }
+
+  if (!key || !value) {
+    throw new Error(
+      "Invalid config set usage. Use either: atlasctl config set <site|email|apikey> <value> or run atlasctl config set for guided setup.",
+    );
+  }
+
+  await handleConfigSet(parseConfigKey(key), value);
+}
+
+export function buildProgram(): Command {
+  const program = new Command();
+
+  program
+    .name("atlasctl")
+    .description("Atlassian CLI for Confluence page exports")
+    .version(VERSION)
+    .option("--help-llm", "print concise LLM-focused usage guidance")
+    .showHelpAfterError();
+
+  const configCommand = program.command("config").description("Manage local CLI configuration");
+
+  configCommand
+    .command("set")
+    .description("Set one config value, or run guided setup with no arguments")
+    .argument("[key]", "config key: site, email, apikey")
+    .argument("[value]", "config value")
+    .action(async (key?: string, value?: string) => {
+      await handleConfigSetCommand(key, value);
+    });
+
+  configCommand
+    .command("get")
+    .description("Get a config value")
+    .argument("<key>", "config key", parseConfigKey)
+    .action(async (key: ConfigKey) => {
+      await handleConfigGet(key);
+    });
+
+  configCommand
+    .command("show")
+    .description("Show current config (API key is always redacted)")
+    .action(async () => {
+      await handleConfigShow();
+    });
+
+  const confluenceCommand = program.command("confluence").description("Confluence operations");
+  const pageCommand = confluenceCommand.command("page").description("Confluence page operations");
+
+  pageCommand
+    .command("fetch")
+    .description("Fetch a Confluence page and all comments")
+    .argument("<id-or-url>", "numeric page ID or full Confluence page URL")
+    .option("--output <file>", "write JSON result to file")
+    .option("--pretty", "pretty-print JSON output")
+    .action(async (idOrUrl: string, options: { output?: string; pretty?: boolean }) => {
+      await handlePageFetch(idOrUrl, options);
+    });
+
+  return program;
+}
+
+export async function run(argv = process.argv): Promise<void> {
+  if (argv.includes("--help-llm")) {
+    process.stdout.write(`${getLlmHelpText()}\n`);
+    return;
+  }
+
+  const program = buildProgram();
+  await program.parseAsync(argv);
+}
+
+if (import.meta.main) {
+  run().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exit(1);
+  });
+}

package/src/config.ts

@@ -0,0 +1,184 @@
+import { chmod, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import type { AtlasCtlConfig, RequiredConfig } from "./types";
+
+export const CONFIG_FILENAME = ".atlasctl.json";
+export const CONFIG_KEYS = ["site", "email", "apikey"] as const;
+
+export type ConfigKey = (typeof CONFIG_KEYS)[number];
+
+interface ConfigPathOptions {
+  configPath?: string;
+  homeDir?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function resolveConfigPath(options: ConfigPathOptions = {}): string {
+  if (options.configPath) {
+    return options.configPath;
+  }
+
+  const home = options.homeDir ?? homedir();
+  return path.join(home, CONFIG_FILENAME);
+}
+
+export function normalizeSite(input: string): string {
+  const value = input.trim();
+  if (!value) {
+    throw new Error("Site cannot be empty");
+  }
+
+  try {
+    const url = value.includes("://")
+      ? new URL(value)
+      : new URL(`https://${value}`);
+
+    if (!url.hostname) {
+      throw new Error();
+    }
+
+    return url.host.toLowerCase();
+  } catch {
+    throw new Error("Invalid site. Use a hostname like your-domain.atlassian.net");
+  }
+}
+
+function normalizeEmail(input: string): string {
+  const value = input.trim();
+  const isEmail = /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(value);
+  if (!isEmail) {
+    throw new Error("Invalid email address");
+  }
+  return value;
+}
+
+function normalizeApiKey(input: string): string {
+  const value = input.trim();
+  if (!value) {
+    throw new Error("API key cannot be empty");
+  }
+  return value;
+}
+
+export function normalizeConfigValue(key: ConfigKey, rawValue: string): string {
+  if (key === "site") {
+    return normalizeSite(rawValue);
+  }
+
+  if (key === "email") {
+    return normalizeEmail(rawValue);
+  }
+
+  return normalizeApiKey(rawValue);
+}
+
+function normalizeConfig(raw: unknown): AtlasCtlConfig {
+  if (!isRecord(raw)) {
+    throw new Error("Config must be a JSON object");
+  }
+
+  const config: AtlasCtlConfig = {};
+
+  if (typeof raw.site === "string" && raw.site.trim()) {
+    config.site = normalizeSite(raw.site);
+  }
+
+  if (typeof raw.email === "string" && raw.email.trim()) {
+    config.email = normalizeEmail(raw.email);
+  }
+
+  if (typeof raw.apikey === "string" && raw.apikey.trim()) {
+    config.apikey = normalizeApiKey(raw.apikey);
+  }
+
+  return config;
+}
+
+export async function readConfig(
+  options: ConfigPathOptions = {},
+): Promise<AtlasCtlConfig> {
+  const configPath = resolveConfigPath(options);
+
+  let raw: string;
+  try {
+    raw = await readFile(configPath, "utf8");
+  } catch (error) {
+    const fileError = error as NodeJS.ErrnoException;
+    if (fileError.code === "ENOENT") {
+      return {};
+    }
+    throw new Error(`Unable to read config at ${configPath}: ${fileError.message}`);
+  }
+
+  try {
+    const parsed = JSON.parse(raw);
+    return normalizeConfig(parsed);
+  } catch (error) {
+    throw new Error(
+      `Invalid config at ${configPath}. Ensure it is valid JSON with site/email/apikey strings.`,
+    );
+  }
+}
+
+export async function writeConfig(
+  config: AtlasCtlConfig,
+  options: ConfigPathOptions = {},
+): Promise<string> {
+  const configPath = resolveConfigPath(options);
+  const normalized = normalizeConfig(config);
+  const content = `${JSON.stringify(normalized, null, 2)}\n`;
+
+  await writeFile(configPath, content, { mode: 0o600 });
+
+  try {
+    await chmod(configPath, 0o600);
+  } catch {
+    // Best effort permission hardening.
+  }
+
+  return configPath;
+}
+
+export async function setConfigValue(
+  key: ConfigKey,
+  rawValue: string,
+  options: ConfigPathOptions = {},
+): Promise<string> {
+  const config = await readConfig(options);
+  config[key] = normalizeConfigValue(key, rawValue);
+
+  return writeConfig(config, options);
+}
+
+export function maskConfig(config: AtlasCtlConfig): AtlasCtlConfig {
+  if (!config.apikey) {
+    return { ...config };
+  }
+
+  return {
+    ...config,
+    apikey: "***hidden***",
+  };
+}
+
+export function requireFetchConfig(config: AtlasCtlConfig): RequiredConfig {
+  const missing: ConfigKey[] = [];
+
+  for (const key of CONFIG_KEYS) {
+    if (!config[key]) {
+      missing.push(key);
+    }
+  }
+
+  if (missing.length > 0) {
+    throw new Error(
+      `Missing required config values: ${missing.join(", ")}. Set each with: atlasctl config set <site|email|apikey> <value>`,
+    );
+  }
+
+  return config as RequiredConfig;
+}

package/src/confluence.ts

@@ -0,0 +1,206 @@
+import type { Comment, PageExport, RequiredConfig } from "./types";
+
+interface ApiClient {
+  baseUrl: string;
+  apiGet: (pathOrUrl: string) => Promise<any>;
+  fetchAllPages: (path: string) => Promise<any[]>;
+}
+
+interface ParsedPageInput {
+  pageId: string;
+  hostFromUrl?: string;
+}
+
+export function parsePageInput(idOrUrl: string): ParsedPageInput {
+  const value = idOrUrl.trim();
+  if (/^\d+$/.test(value)) {
+    return { pageId: value };
+  }
+
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(
+      "Invalid page identifier. Provide a numeric page ID or a full Confluence page URL.",
+    );
+  }
+
+  const fromPath = url.pathname.match(/\/pages\/(\d+)(?:\/|$)/)?.[1];
+  const fromQuery = url.searchParams.get("pageId") ?? undefined;
+  const pageId = fromPath ?? fromQuery;
+
+  if (!pageId || !/^\d+$/.test(pageId)) {
+    throw new Error("Could not extract a numeric page ID from the provided URL.");
+  }
+
+  return {
+    pageId,
+    hostFromUrl: url.host.toLowerCase(),
+  };
+}
+
+export function resolvePageIdForSite(
+  idOrUrl: string,
+  configuredSite: string,
+): string {
+  const parsed = parsePageInput(idOrUrl);
+
+  if (parsed.hostFromUrl && parsed.hostFromUrl !== configuredSite.toLowerCase()) {
+    throw new Error(
+      `URL host mismatch: URL uses ${parsed.hostFromUrl} but config site is ${configuredSite}.`,
+    );
+  }
+
+  return parsed.pageId;
+}
+
+function countComments(comments: Comment[]): number {
+  return comments.reduce((total, comment) => {
+    return total + 1 + countComments(comment.children);
+  }, 0);
+}
+
+function parseComment(raw: any): Comment {
+  const ext = raw.extensions ?? {};
+  let inlineContext: Comment["inlineContext"];
+
+  if (ext.inlineProperties) {
+    inlineContext = {
+      textSelection: ext.inlineProperties.originalSelection ?? "",
+      markerRef: ext.inlineProperties.markerRef ?? "",
+      resolved: ext.resolution?.status === "resolved",
+    };
+  }
+
+  return {
+    id: raw.id,
+    title: raw.title ?? "",
+    author:
+      raw.version?.by?.displayName ??
+      raw.history?.createdBy?.displayName ??
+      "unknown",
+    created: raw.version?.when ?? raw.history?.createdDate ?? "",
+    updated: raw.version?.when ?? "",
+    bodyHtml: raw.body?.storage?.value ?? raw.body?.view?.value ?? "",
+    inlineContext,
+    children: [],
+  };
+}
+
+function normalizePaginationLink(next: string): string {
+  if (next.startsWith("http://") || next.startsWith("https://")) {
+    return next;
+  }
+
+  if (next.startsWith("/wiki/")) {
+    return next.slice("/wiki".length);
+  }
+
+  return next;
+}
+
+function createClient(config: RequiredConfig): ApiClient {
+  const baseUrl = `https://${config.site}/wiki`;
+  const auth = Buffer.from(`${config.email}:${config.apikey}`).toString("base64");
+
+  const headers = {
+    Authorization: `Basic ${auth}`,
+    Accept: "application/json",
+  };
+
+  async function apiGet(pathOrUrl: string): Promise<any> {
+    const url =
+      pathOrUrl.startsWith("http://") || pathOrUrl.startsWith("https://")
+        ? pathOrUrl
+        : `${baseUrl}${pathOrUrl.startsWith("/") ? pathOrUrl : `/${pathOrUrl}`}`;
+
+    const response = await fetch(url, { headers });
+
+    if (!response.ok) {
+      throw new Error(`Confluence API error ${response.status} ${response.statusText}: GET ${url}`);
+    }
+
+    return response.json();
+  }
+
+  async function fetchAllPages(path: string): Promise<any[]> {
+    const results: any[] = [];
+    let next: string | null = path;
+
+    while (next) {
+      const page = await apiGet(next);
+      if (Array.isArray(page.results)) {
+        results.push(...page.results);
+      }
+
+      next = page._links?.next ? normalizePaginationLink(page._links.next) : null;
+    }
+
+    return results;
+  }
+
+  return {
+    baseUrl,
+    apiGet,
+    fetchAllPages,
+  };
+}
+
+async function fetchReplies(client: ApiClient, commentId: string): Promise<Comment[]> {
+  const rawReplies = await client.fetchAllPages(
+    `/rest/api/content/${commentId}/child/comment?expand=body.storage,version,extensions.inlineProperties,extensions.resolution&limit=100`,
+  );
+
+  const replies: Comment[] = [];
+  for (const raw of rawReplies) {
+    const reply = parseComment(raw);
+    reply.children = await fetchReplies(client, raw.id);
+    replies.push(reply);
+  }
+
+  return replies;
+}
+
+export async function fetchConfluencePage(
+  config: RequiredConfig,
+  idOrUrl: string,
+): Promise<PageExport> {
+  const pageId = resolvePageIdForSite(idOrUrl, config.site);
+  const client = createClient(config);
+
+  const page = await client.apiGet(
+    `/rest/api/content/${pageId}?expand=body.storage,version,history,space,metadata.labels`,
+  );
+
+  const rawComments = await client.fetchAllPages(
+    `/rest/api/content/${pageId}/child/comment?expand=body.storage,version,extensions.inlineProperties,extensions.resolution&limit=100`,
+  );
+
+  const comments: Comment[] = [];
+  for (const raw of rawComments) {
+    const comment = parseComment(raw);
+    comment.children = await fetchReplies(client, raw.id);
+    comments.push(comment);
+  }
+
+  return {
+    page: {
+      id: page.id,
+      title: page.title,
+      space: page.space?.key ?? "",
+      url: `${client.baseUrl}${page._links?.webui ?? ""}`,
+      author: page.version?.by?.displayName ?? "unknown",
+      created: page.history?.createdDate ?? page.version?.when ?? "",
+      lastUpdated: page.version?.when ?? "",
+      version: page.version?.number ?? 1,
+      labels: (page.metadata?.labels?.results ?? []).map((label: any) => label.name),
+      bodyHtml: page.body?.storage?.value ?? "",
+    },
+    comments,
+    meta: {
+      fetchedAt: new Date().toISOString(),
+      totalComments: countComments(comments),
+    },
+  };
+}

package/src/llm-help.ts

@@ -0,0 +1,42 @@
+export function getLlmHelpText(): string {
+  return `atlasctl (LLM Quick Guide)
+
+Purpose
+- Fetch a Confluence page plus full comment tree (including inline comments) as JSON.
+
+Required config
+- File: ~/.atlasctl.json
+- Keys: site, email, apikey
+
+Fast path
+- atlasctl config set
+- atlasctl confluence page fetch <page-id-or-url> --pretty
+
+Non-interactive setup
+- atlasctl config set site <your-domain.atlassian.net>
+- atlasctl config set email <you@example.com>
+- atlasctl config set apikey <token>
+
+Read config
+- atlasctl config show
+- atlasctl config get site
+- atlasctl config get email
+- atlasctl config get apikey  (always prints ***hidden***)
+
+Fetch
+- atlasctl confluence page fetch <id-or-url> [--output <file>] [--pretty]
+
+Input rules
+- id-or-url can be numeric page ID, /pages/<id>/ URL, or ?pageId=<id> URL.
+- URL host must match configured site.
+
+Output
+- page, comments (recursive), meta.
+- inline comments map to comment.inlineContext: textSelection, markerRef, resolved.
+
+Common failures
+- Missing config keys: set site/email/apikey.
+- Invalid URL or no page ID in URL.
+- URL host mismatch with configured site.
+- Guided config in non-TTY: use explicit config set key/value commands.`;
+}

package/src/types.ts

@@ -0,0 +1,46 @@
+export interface AtlasCtlConfig {
+  site?: string;
+  email?: string;
+  apikey?: string;
+}
+
+export interface RequiredConfig {
+  site: string;
+  email: string;
+  apikey: string;
+}
+
+export interface Comment {
+  id: string;
+  title: string;
+  author: string;
+  created: string;
+  updated: string;
+  bodyHtml: string;
+  inlineContext?: {
+    textSelection: string;
+    markerRef: string;
+    resolved: boolean;
+  };
+  children: Comment[];
+}
+
+export interface PageExport {
+  page: {
+    id: string;
+    title: string;
+    space: string;
+    url: string;
+    author: string;
+    created: string;
+    lastUpdated: string;
+    version: number;
+    labels: string[];
+    bodyHtml: string;
+  };
+  comments: Comment[];
+  meta: {
+    fetchedAt: string;
+    totalComments: number;
+  };
+}