alphamilk 0.0.3 → 0.0.5

package/README.md

@@ -0,0 +1,146 @@
+# alphamilk
+
+AI-powered SEO research from your terminal. A thin CLI proxy to the Alpha Milk Worker API.
+
+## Installation
+
+```bash
+# Run directly without installing
+npx alphamilk --help
+
+# Or install globally
+npm install -g alphamilk
+```
+
+## Authentication
+
+All commands (except `login` and `logout`) require an active session. Authenticate with your access token:
+
+```bash
+alphamilk login --token <your-token-id>
+```
+
+This creates a session stored at `~/.config/alphamilk/session.json`. Sessions expire after 24 hours by default.
+
+Check your current session:
+
+```bash
+alphamilk session
+```
+
+Clear your session:
+
+```bash
+alphamilk logout
+```
+
+## Commands
+
+### `login` -- Authenticate with your access token
+
+```bash
+alphamilk login --token <tokenId>
+alphamilk login -t <tokenId>
+```
+
+Calls `GET /milk/create-session/<tokenId>` and stores the returned session locally.
+
+### `logout` -- Clear your session
+
+```bash
+alphamilk logout
+```
+
+Removes the local session file.
+
+### `session` -- Show current session info
+
+```bash
+alphamilk session
+```
+
+Displays the session ID, token (truncated), base URL, and expiry.
+
+### `playbooks` -- List available research playbooks
+
+```bash
+alphamilk playbooks
+```
+
+### `playbook` -- Open a playbook or its report template
+
+```bash
+# Get playbook content
+alphamilk playbook competitor-discovery
+
+# Get the report template for a playbook
+alphamilk playbook competitor-discovery --report
+alphamilk playbook competitor-discovery -r
+```
+
+### `probe` -- Execute a research probe
+
+```bash
+alphamilk probe serp-google -p keyword=seo -p location_code=2840
+alphamilk probe ranked-keywords --param target=example.com
+```
+
+Parameters are passed as repeatable `--param key=value` (or `-p key=value`) pairs. The probe is executed via `POST /milk/probe/<sessionId>/<slug>` with parameters sent as a JSON body.
+
+### `report` -- Save and retrieve research reports
+
+```bash
+# Save a report from a file (recommended)
+alphamilk report save --name "Competitor Analysis" --file ./report.md
+
+# Save a report with inline content
+alphamilk report save --name "Quick Note" --content "# Summary\n\nKey findings..."
+
+# Retrieve a saved report
+alphamilk report get <reportId>
+```
+
+You must provide exactly one of `--file` or `--content` when saving.
+
+### `artifact` -- Save and retrieve research artifacts
+
+```bash
+# Save an artifact
+alphamilk artifact save --type domains --tags "competitors,direct" --data "example.com,other.com"
+
+# List artifacts with optional filters
+alphamilk artifact list
+alphamilk artifact list --type domains
+alphamilk artifact list --tag competitors
+
+# Retrieve a specific artifact
+alphamilk artifact get <artifactId>
+```
+
+Artifact types are `domains` or `keywords`. Tags and data are comma-separated.
+
+## How It Works
+
+The CLI is a thin HTTP proxy. Every command translates to a GET or POST request to the Alpha Milk Worker API at `https://alphamilk.ai/milk/*`. Responses (typically markdown) are printed directly to stdout.
+
+All requests include two custom headers for server-side identification:
+- `X-AlphaMilk-Client: cli`
+- `X-AlphaMilk-CLI-Version: <version>`
+
+## Build
+
+```bash
+# Build the single-file bundle
+pnpm build
+
+# Run in development mode (via tsx)
+pnpm dev
+
+# Type check
+pnpm check
+
+# Run tests
+pnpm test
+```
+
+The build uses esbuild to bundle all source into a single `dist/cli.js` file with a Node.js shebang prepended.

package/dist/cli.js

@@ -44,7 +44,7 @@ function clearSession() {
 // src/api.ts
 import { Effect, Data } from "effect";
 import { HttpClient, HttpClientRequest } from "@effect/platform";
-var CLI_VERSION = "0.0.1";
+var CLI_VERSION = "0.0.3";
 var ApiError = class extends Data.TaggedError("ApiError") {
 };
 var apiGet = (baseUrl, path3, params) => Effect.gen(function* () {
@@ -68,6 +68,21 @@ var apiGet = (baseUrl, path3, params) => Effect.gen(function* () {
   }
   return body;
 });
+var apiPut = (baseUrl, path3, body) => Effect.gen(function* () {
+  const client = yield* HttpClient.HttpClient;
+  const url = new URL(path3, baseUrl);
+  const request = HttpClientRequest.put(url.toString()).pipe(
+    HttpClientRequest.setHeader("X-AlphaMilk-Client", "cli"),
+    HttpClientRequest.setHeader("X-AlphaMilk-CLI-Version", CLI_VERSION),
+    HttpClientRequest.bodyUnsafeJson(body)
+  );
+  const response = yield* client.execute(request).pipe(Effect.scoped);
+  const responseBody = yield* response.text;
+  if (response.status >= 400) {
+    return yield* Effect.fail(new ApiError({ statusCode: response.status, message: responseBody }));
+  }
+  return responseBody;
+});
 var apiPost = (baseUrl, path3, body) => Effect.gen(function* () {
   const client = yield* HttpClient.HttpClient;
   const url = new URL(path3, baseUrl);
@@ -217,18 +232,30 @@ var playbookReport = Options.boolean("report").pipe(
   Options.withDefault(false),
   Options.withDescription("Get the report template instead of playbook content")
 );
+var playbookStep = Options.text("step").pipe(
+  Options.withAlias("s"),
+  Options.withDescription("Get a single step's instructions by step ID"),
+  Options.optional
+);
 var playbookCommand = Command.make(
   "playbook",
-  { slug: playbookSlug, report: playbookReport },
-  ({ slug, report }) => Effect3.gen(function* () {
+  { slug: playbookSlug, report: playbookReport, step: playbookStep },
+  ({ slug, report, step }) => Effect3.gen(function* () {
     const session = yield* requireSession;
-    const urlPath = report ? `/milk/playbook/${session.sessionId}/${slug}/report` : `/milk/playbook/${session.sessionId}/${slug}`;
+    let urlPath;
+    if (report) {
+      urlPath = `/milk/playbook/${session.sessionId}/${slug}/report`;
+    } else if (step._tag === "Some") {
+      urlPath = `/milk/playbook/${session.sessionId}/${slug}?step=${encodeURIComponent(step.value)}`;
+    } else {
+      urlPath = `/milk/playbook/${session.sessionId}/${slug}`;
+    }
     const response = yield* apiGet(session.baseUrl, urlPath).pipe(
       handleApiError("Failed to get playbook")
     );
     yield* Console2.log(response);
   })
-).pipe(Command.withDescription("Open a playbook or its report template"));
+).pipe(Command.withDescription("Open a playbook, a specific step, or its report template"));
 var probeSlug = Args.text({ name: "slug" }).pipe(
   Args.withDescription("Probe slug (e.g., serp-google, ranked-keywords)")
 );
@@ -252,99 +279,153 @@ var probeCommand = Command.make(
       session.baseUrl,
       `/milk/probe/${session.sessionId}/${slug}`,
       queryParams
-    ).pipe(handleApiError("Skill execution failed"));
+    ).pipe(handleApiError("Probe execution failed"));
     yield* Console2.log(response);
   })
 ).pipe(Command.withDescription("Execute a research probe"));
-var reportSaveName = Options.text("name").pipe(
+var artifactSaveType = Options.choice("type", ["domains", "keywords", "document", "report", "metrics"]).pipe(
+  Options.withDescription("Artifact type")
+);
+var artifactSaveTitle = Options.text("title").pipe(
   Options.withAlias("n"),
-  Options.withDescription("Report title/name")
+  Options.withDescription("Artifact title (required for document/report)"),
+  Options.optional
 );
-var reportSaveContent = Options.text("content").pipe(
-  Options.withAlias("c"),
-  Options.withDescription("Full markdown report content (inline). Use --file instead for file-based input."),
+var artifactSaveTags = Options.text("tags").pipe(
+  Options.withDescription("Comma-separated tags (e.g., competitors,direct)")
+);
+var artifactSaveData = Options.text("data").pipe(
+  Options.withAlias("d"),
+  Options.withDescription("Comma-separated data items (for domains/keywords)"),
   Options.optional
 );
-var reportSaveFile = Options.text("file").pipe(
+var artifactSaveFile = Options.text("file").pipe(
   Options.withAlias("f"),
-  Options.withDescription("Path to a markdown file containing the report content"),
+  Options.withDescription("Path to a file (markdown for document, JSON for report/metrics)"),
+  Options.optional
+);
+var artifactSaveContent = Options.text("content").pipe(
+  Options.withAlias("c"),
+  Options.withDescription("Inline content string (for document type)"),
   Options.optional
 );
-var reportSaveCommand = Command.make(
+var artifactSaveCommand = Command.make(
   "save",
-  { name: reportSaveName, content: reportSaveContent, file: reportSaveFile },
-  ({ name, content, file }) => Effect3.gen(function* () {
+  { type: artifactSaveType, title: artifactSaveTitle, tags: artifactSaveTags, data: artifactSaveData, file: artifactSaveFile, content: artifactSaveContent },
+  ({ type, title, tags, data, file, content }) => Effect3.gen(function* () {
     const session = yield* requireSession;
-    let resolvedContent;
-    if (content._tag === "Some" && file._tag === "Some") {
-      return yield* exitWithError(
-        'Cannot use both --content and --file. Provide one or the other.\n\n  --file report.md      Read content from a markdown file\n  --content "# ..."     Pass content inline as a string'
-      );
-    }
-    if (content._tag === "None" && file._tag === "None") {
-      return yield* exitWithError(
-        'Missing report content. Provide one of:\n\n  --file report.md      Read content from a markdown file (recommended)\n  --content "# ..."     Pass content inline as a string\n\nExample:\n  alphamilk report save --name "My Report" --file ./report.md'
-      );
+    const body = {
+      type,
+      tags: tags.split(",").map((t) => t.trim())
+    };
+    if (title._tag === "Some") {
+      body.title = title.value;
     }
-    if (file._tag === "Some") {
-      resolvedContent = yield* readReportFile(file.value);
-    } else {
-      resolvedContent = content.value;
+    if (type === "domains" || type === "keywords") {
+      if (data._tag === "None") {
+        return yield* exitWithError(
+          `--data is required for ${type} artifacts.
+
+Example: alphamilk artifact save --type ${type} --tags step:discovery --data "example.com,other.com"`
+        );
+      }
+      body.data = data.value.split(",").map((d) => d.trim());
+    } else if (type === "document") {
+      if (file._tag === "None" && content._tag === "None") {
+        return yield* exitWithError(
+          'Document artifacts require --file or --content.\n\nExample:\n  alphamilk artifact save --type document --title "Analysis" --tags step:analysis --file ./analysis.md\n  alphamilk artifact save --type document --title "Notes" --tags notes --content "# Notes\\n..."'
+        );
+      }
+      if (file._tag === "Some" && content._tag === "Some") {
+        return yield* exitWithError("Cannot use both --file and --content. Provide one or the other.");
+      }
+      if (file._tag === "Some") {
+        body.content = yield* readReportFile(file.value);
+      } else {
+        body.content = content.value;
+      }
+    } else if (type === "report") {
+      if (file._tag === "None") {
+        return yield* exitWithError(
+          'Report artifacts require --file with a JSON manifest.\n\nExample: alphamilk artifact save --type report --title "Final Report" --tags report --file ./manifest.json'
+        );
+      }
+      body.content = yield* readReportFile(file.value);
+    } else if (type === "metrics") {
+      if (file._tag === "Some") {
+        body.content = yield* readReportFile(file.value);
+      } else if (data._tag === "Some") {
+        const rows = data.value.split(",").map((pair) => {
+          const [label, rest] = pair.trim().split(":");
+          const value = parseFloat(rest ?? "0");
+          return { label: label?.trim() ?? "", value: isNaN(value) ? 0 : value };
+        });
+        body.content = JSON.stringify(rows);
+      } else {
+        return yield* exitWithError(
+          'Metrics artifacts require --file (JSON) or --data (label:value pairs).\n\nExample:\n  alphamilk artifact save --type metrics --tags traffic --file ./metrics.json\n  alphamilk artifact save --type metrics --tags traffic --data "example.com:45000,other.com:12000"'
+        );
+      }
     }
     const response = yield* apiPost(
       session.baseUrl,
-      `/milk/report/${session.sessionId}`,
-      { name, content: resolvedContent }
-    ).pipe(handleApiError("Failed to save report"));
+      `/milk/artifact/${session.sessionId}`,
+      body
+    ).pipe(handleApiError("Failed to save artifact"));
     yield* Console2.log(response);
   })
-).pipe(Command.withDescription("Save a research report"));
-var reportGetId = Args.text({ name: "reportId" }).pipe(
-  Args.withDescription("Report ID")
+).pipe(Command.withDescription("Save a research artifact"));
+var artifactUpdateId = Args.text({ name: "artifactId" }).pipe(
+  Args.withDescription("Artifact ID to update")
 );
-var reportGetCommand = Command.make(
-  "get",
-  { reportId: reportGetId },
-  ({ reportId }) => Effect3.gen(function* () {
-    const session = yield* requireSession;
-    const response = yield* apiGet(
-      session.baseUrl,
-      `/milk/report/${session.sessionId}/${reportId}`
-    ).pipe(handleApiError("Failed to get report"));
-    yield* Console2.log(response);
-  })
-).pipe(Command.withDescription("Retrieve a saved report"));
-var reportCommand = Command.make("report").pipe(
-  Command.withDescription("Save and retrieve research reports"),
-  Command.withSubcommands([reportSaveCommand, reportGetCommand])
+var artifactUpdateTitle = Options.text("title").pipe(
+  Options.withAlias("n"),
+  Options.withDescription("Updated title"),
+  Options.optional
 );
-var artifactSaveType = Options.choice("type", ["domains", "keywords"]).pipe(
-  Options.withDescription("Artifact type")
+var artifactUpdateFile = Options.text("file").pipe(
+  Options.withAlias("f"),
+  Options.withDescription("Path to updated content file"),
+  Options.optional
 );
-var artifactSaveTags = Options.text("tags").pipe(
-  Options.withDescription("Comma-separated tags (e.g., competitors,direct)")
+var artifactUpdateContent = Options.text("content").pipe(
+  Options.withAlias("c"),
+  Options.withDescription("Updated inline content"),
+  Options.optional
 );
-var artifactSaveData = Options.text("data").pipe(
+var artifactUpdateData = Options.text("data").pipe(
   Options.withAlias("d"),
-  Options.withDescription("Comma-separated data items (e.g., example.com,other.com)")
+  Options.withDescription("Updated comma-separated data items"),
+  Options.optional
 );
-var artifactSaveCommand = Command.make(
-  "save",
-  { type: artifactSaveType, tags: artifactSaveTags, data: artifactSaveData },
-  ({ type, tags, data }) => Effect3.gen(function* () {
+var artifactUpdateCommand = Command.make(
+  "update",
+  { artifactId: artifactUpdateId, title: artifactUpdateTitle, file: artifactUpdateFile, content: artifactUpdateContent, data: artifactUpdateData },
+  ({ artifactId, title, file, content, data }) => Effect3.gen(function* () {
     const session = yield* requireSession;
-    const response = yield* apiPost(
+    const body = {};
+    if (title._tag === "Some") body.title = title.value;
+    if (file._tag === "Some") {
+      body.content = yield* readReportFile(file.value);
+    } else if (content._tag === "Some") {
+      body.content = content.value;
+    }
+    if (data._tag === "Some") {
+      body.data = data.value.split(",").map((d) => d.trim());
+    }
+    if (Object.keys(body).length === 0) {
+      return yield* exitWithError(
+        "Nothing to update. Provide at least one of: --title, --file, --content, --data"
+      );
+    }
+    const response = yield* apiPut(
       session.baseUrl,
-      `/milk/artifact/${session.sessionId}`,
-      {
-        type,
-        tags: tags.split(",").map((t) => t.trim()),
-        data: data.split(",").map((d) => d.trim())
-      }
-    ).pipe(handleApiError("Failed to save artifact"));
+      `/milk/artifact/${session.sessionId}/${artifactId}`,
+      body
+    ).pipe(handleApiError("Failed to update artifact"));
     yield* Console2.log(response);
   })
-).pipe(Command.withDescription("Save a research artifact"));
+).pipe(Command.withDescription("Update an existing artifact"));
 var artifactGetId = Args.text({ name: "artifactId" }).pipe(
   Args.withDescription("Artifact ID")
 );
@@ -360,6 +441,21 @@ var artifactGetCommand = Command.make(
     yield* Console2.log(response);
   })
 ).pipe(Command.withDescription("Retrieve a saved artifact"));
+var artifactRenderId = Args.text({ name: "artifactId" }).pipe(
+  Args.withDescription("Artifact ID to render")
+);
+var artifactRenderCommand = Command.make(
+  "render",
+  { artifactId: artifactRenderId },
+  ({ artifactId }) => Effect3.gen(function* () {
+    const session = yield* requireSession;
+    const response = yield* apiGet(
+      session.baseUrl,
+      `/milk/artifact/${session.sessionId}/${artifactId}/render`
+    ).pipe(handleApiError("Failed to render artifact"));
+    yield* Console2.log(response);
+  })
+).pipe(Command.withDescription("Render an artifact (assembles reports from referenced artifacts)"));
 var artifactListType = Options.text("type").pipe(
   Options.withDescription("Filter by artifact type"),
   Options.optional
@@ -385,8 +481,84 @@ var artifactListCommand = Command.make(
   })
 ).pipe(Command.withDescription("List saved artifacts"));
 var artifactCommand = Command.make("artifact").pipe(
-  Command.withDescription("Save and retrieve research artifacts"),
-  Command.withSubcommands([artifactSaveCommand, artifactGetCommand, artifactListCommand])
+  Command.withDescription("Save, update, and retrieve research artifacts"),
+  Command.withSubcommands([artifactSaveCommand, artifactUpdateCommand, artifactGetCommand, artifactRenderCommand, artifactListCommand])
+);
+var planSaveFile = Options.text("file").pipe(
+  Options.withAlias("f"),
+  Options.withDescription("Path to an XML file containing the plan")
+);
+var planSaveCommand = Command.make(
+  "save",
+  { file: planSaveFile },
+  ({ file }) => Effect3.gen(function* () {
+    const session = yield* requireSession;
+    const xmlContent = yield* readReportFile(file);
+    const response = yield* apiPost(
+      session.baseUrl,
+      `/milk/plan/${session.sessionId}/save`,
+      { xml: xmlContent }
+    ).pipe(handleApiError("Failed to save plan"));
+    yield* Console2.log(response);
+  })
+).pipe(Command.withDescription("Save a plan from an XML file"));
+var planStatusCommand = Command.make(
+  "status",
+  {},
+  () => Effect3.gen(function* () {
+    const session = yield* requireSession;
+    const response = yield* apiPost(
+      session.baseUrl,
+      `/milk/plan/${session.sessionId}/status`,
+      {}
+    ).pipe(handleApiError("Failed to get plan status"));
+    yield* Console2.log(response);
+  })
+).pipe(Command.withDescription("View current plan status"));
+var planCheckStepId = Args.text({ name: "stepId" }).pipe(
+  Args.withDescription("Step ID to mark as done (e.g., broad-discovery)")
+);
+var planCheckCommand = Command.make(
+  "check",
+  { stepId: planCheckStepId },
+  ({ stepId }) => Effect3.gen(function* () {
+    const session = yield* requireSession;
+    const response = yield* apiPost(
+      session.baseUrl,
+      `/milk/plan/${session.sessionId}/check/${stepId}`,
+      {}
+    ).pipe(handleApiError("Failed to check step"));
+    yield* Console2.log(response);
+  })
+).pipe(Command.withDescription("Mark a plan step as done"));
+var planSkipStepId = Args.text({ name: "stepId" }).pipe(
+  Args.withDescription("Step ID to skip (e.g., validate-gaps)")
+);
+var planSkipReason = Options.text("reason").pipe(
+  Options.withAlias("r"),
+  Options.withDescription("Reason for skipping this step"),
+  Options.optional
+);
+var planSkipCommand = Command.make(
+  "skip",
+  { stepId: planSkipStepId, reason: planSkipReason },
+  ({ stepId, reason }) => Effect3.gen(function* () {
+    const session = yield* requireSession;
+    const body = {};
+    if (reason._tag === "Some") {
+      body.reason = reason.value;
+    }
+    const response = yield* apiPost(
+      session.baseUrl,
+      `/milk/plan/${session.sessionId}/skip/${stepId}`,
+      body
+    ).pipe(handleApiError("Failed to skip step"));
+    yield* Console2.log(response);
+  })
+).pipe(Command.withDescription("Skip a plan step with an optional reason"));
+var planCommand = Command.make("plan").pipe(
+  Command.withDescription("Save and manage research plans"),
+  Command.withSubcommands([planSaveCommand, planStatusCommand, planCheckCommand, planSkipCommand])
 );
 var logoutCommand = Command.make(
   "logout",
@@ -405,13 +577,13 @@ var root = Command.make("alphamilk").pipe(
     playbooksCommand,
     playbookCommand,
     probeCommand,
-    reportCommand,
-    artifactCommand
+    artifactCommand,
+    planCommand
   ])
 );
 var cli = Command.run(root, {
   name: "alphamilk",
-  version: "0.0.1"
+  version: "0.0.3"
 });
 var MainLayer = Layer.mergeAll(
   NodeContext.layer,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alphamilk",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "license": "MIT",
   "description": "Alpha Milk CLI - AI-powered SEO research from your terminal",