atlasctl 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atlasctl",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Atlassian CLI for Confluence page exports with comments",
   "type": "module",
   "packageManager": "bun@1.3.8",
@@ -21,6 +21,7 @@
     "test": "bun test"
   },
   "dependencies": {
+    "@modeltoolsprotocol/sdk": "0.2.0",
     "commander": "^14.0.3"
   }
 }

package/src/cli.ts

@@ -13,9 +13,9 @@ import {
   writeConfig,
 } from "./config";
 import { fetchConfluencePage } from "./confluence";
-import { getLlmHelpText } from "./llm-help";
+import { withDescribe, type DescribeOptions } from "@modeltoolsprotocol/sdk";
 
-const VERSION = "0.1.1";
+const VERSION = "0.2.0";
 
 function parseConfigKey(value: string): ConfigKey {
   if (!CONFIG_KEYS.includes(value as ConfigKey)) {
@@ -144,6 +144,83 @@ async function handleConfigSetCommand(key?: string, value?: string): Promise<voi
   await handleConfigSet(parseConfigKey(key), value);
 }
 
+export const DESCRIBE_OPTIONS: DescribeOptions = {
+  commands: {
+    "config set": {
+      examples: [
+        { description: "Interactive guided setup", command: "atlasctl config set" },
+        { description: "Set site", command: "atlasctl config set site your-domain.atlassian.net" },
+        { description: "Set API key", command: "atlasctl config set apikey your-token" },
+      ],
+    },
+    "config get": {
+      stdout: {
+        contentType: "text/plain",
+        description: "The config value. apikey always prints ***hidden***.",
+      },
+      examples: [
+        { description: "Read configured site", command: "atlasctl config get site", output: "your-domain.atlassian.net" },
+      ],
+    },
+    "config show": {
+      stdout: {
+        contentType: "application/json",
+        description: "All config keys with apikey masked",
+      },
+      examples: [
+        { description: "Display current config", command: "atlasctl config show" },
+      ],
+    },
+    "confluence page get": {
+      argTypes: { output: "path" },
+      stdout: {
+        contentType: "application/json",
+        description: "Page metadata, recursive comment tree, and fetch metadata",
+        schema: {
+          type: "object",
+          required: ["page", "comments", "meta"],
+          properties: {
+            page: {
+              type: "object",
+              properties: {
+                id: { type: "string" },
+                title: { type: "string" },
+                space: { type: "string" },
+                url: { type: "string" },
+                bodyHtml: { type: "string" },
+              },
+            },
+            comments: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  id: { type: "string" },
+                  author: { type: "string" },
+                  bodyHtml: { type: "string" },
+                  inlineContext: { type: "object" },
+                  children: { type: "array" },
+                },
+              },
+            },
+            meta: {
+              type: "object",
+              properties: {
+                fetchedAt: { type: "string" },
+                totalComments: { type: "integer" },
+              },
+            },
+          },
+        },
+      },
+      examples: [
+        { description: "Fetch a page by ID", command: "atlasctl confluence page get 12345 --pretty" },
+        { description: "Fetch by URL, save to file", command: "atlasctl confluence page get https://your-domain.atlassian.net/wiki/spaces/ENG/pages/12345 --output page.json" },
+      ],
+    },
+  },
+};
+
 export function buildProgram(): Command {
   const program = new Command();
 
@@ -151,9 +228,10 @@ export function buildProgram(): Command {
     .name("atlasctl")
     .description("Atlassian CLI for Confluence page exports")
     .version(VERSION)
-    .option("--help-llm", "print concise LLM-focused usage guidance")
     .showHelpAfterError();
 
+  withDescribe(program, DESCRIBE_OPTIONS);
+
   const configCommand = program.command("config").description("Manage local CLI configuration");
 
   configCommand
@@ -197,11 +275,6 @@ export function buildProgram(): Command {
 }
 
 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);
 }

package/src/llm-help.ts

@@ -1,42 +0,0 @@
-export function getLlmHelpText(): string {
-  return `atlasctl (LLM Quick Guide)
-
-Purpose
-- Get 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 get <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 get <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.`;
-}