@mirage-cli/contentdynamite-cli 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @mirage-cli/contentdynamite-cli
+
+## 1.0.0
+
+### Major Changes
+
+- The product's own `ve-dynamite` CLI against the Content Dynamite Workers API, replacing the 0.1.0 port of the Python CLI. First npm release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Brufsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# @mirage-cli/contentdynamite-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`ve-dynamite`, the Content Dynamite CLI: SEO articles, Google Business Profile posts, BOFU landing pages, company profiles, ICP, design systems, part-by-part revisions and featured images, over the Content Dynamite `/api/v1` JSON API. It talks to `https://content-dynamite.alexthecomputer1.workers.dev` unless `--url` or `VE_DYNAMITE_API_URL` names another host.
+
+Stdout is always indented JSON, so pipe it to `jq`. Warnings, progress and hints go to stderr. The exit code is 0 on success and 1 on any error.
+
+> **Money warning:** several commands spend real money (LLM, SERP, crawling, image credits) on every call, and nothing rate limits them. Their help says so and they print a warning when they run. Never script them in a loop.
+
+## Install
+
+```bash
+npm i -g @mirage-cli/contentdynamite-cli    # or: bun add -g @mirage-cli/contentdynamite-cli
+ve-dynamite --help
+```
+
+Runs on Node 18+ or bun. The only dependencies are `commander` and `zod`.
+
+## Sign in
+
+```bash
+ve-dynamite login --email you@example.com --password <pw>   # stores a 24h JWT in ~/.config/ve-dynamite/
+ve-dynamite whoami
+ve-dynamite tokens create --name ci-runner [--expires-days 30]  # a long lived ved_ token for unattended use
+ve-dynamite tokens use ved_xxxxxxxx
+```
+
+Or pass a token per call: `--token ved_xxx` or `VE_DYNAMITE_TOKEN=ved_xxx`. Precedence is `--token`, then `VE_DYNAMITE_TOKEN`, then the stored login. `VE_DYNAMITE_CONFIG_DIR` moves the stored login.
+
+## Commands
+
+| Group | Commands |
+|---|---|
+| root | `login`, `logout`, `whoami`, `upload <file> --type image\|csv` |
+| `tokens` | `create`, `list`, `revoke <id>`, `use <token>` |
+| `users` (admins) | `list`, `set-role <id> --role admin\|normal` |
+| `profiles` | `create`, `list`, `get`, `update`, `delete` |
+| `icp` | `show`, `export`, `regenerate`, `update` |
+| `categories` | `list`, `add` |
+| `design-system` | `show`, `set <profile-id> <zip>`, `rescan`, `clear` |
+| `articles` | `write`, `research-prompt`, `get`, `list`, `watch`, `update`, `delete`, `download`, `export`, `parts`, `reject`, `revisions`, `provenance-audit`, `clean-provenance`, `embed-audit`, `strip-embeds` |
+| `revisions` | `list`, `get`, `watch`, `verdict` |
+| `batches` | `create`, `list`, `get`, `watch`, `delete` |
+| `gbp` | `write`, `batch`, `list`, `get`, `watch`, `update`, `regenerate`, `delete`, `image-options` |
+| `landing-pages` | `write`, `get`, `list`, `watch`, `update`, `delete`, `export`, `deck`, `versions`, `research`, `audit`, `reiterate`, `new-version`, `criteria`, `fix-placeholders`, `fix-images`, `rebrand` |
+| `evals` | `run` |
+| `images` | `edit`, `status`, `commit`, `watch` |
+
+`ve-dynamite <group> <command> --help` documents every flag.
+
+Paid, real money per item: `articles write|reject`, `articles clean-provenance --rewrite`, `batches create`, `gbp write|batch|regenerate`, `landing-pages write|reiterate|new-version|fix-images`, `profiles create`, `icp regenerate`, `design-system set|rescan`, `images edit`, `evals run --judge`.
+
+Generation is asynchronous. A write returns an id at once; `watch` polls until it finishes, or poll `get` yourself about every 10 seconds. A completed article or landing page is `success`, a GBP post is `done`, a revision is `ready`.
+
+## Running inside a host
+
+`buildProgram(options)` returns an unparsed Commander program and `run(argv, options)` runs one command and returns its exit code:
+
+```ts
+import { buildProgram, run, type CostReport } from "@mirage-cli/contentdynamite-cli";
+
+const program = buildProgram({ mount: true, reportCost: (report: CostReport) => record(report) });
+const code = await run(["articles", "get", "41"], { mount: true });
+```
+
+`mount: true` is for agent hosts that inject the credential and the API host. It drops `login`, `logout`, `tokens use`, every `watch` and the `--url` flag, never reads or writes the stored login, takes the token only from `--token` or `VE_DYNAMITE_TOKEN`, requires `-o` on downloads, and words its hints for an agent that polls.
+
+`reportCost` is called once the API accepts paid work, with `{ provider: "contentdynamite", units }`, where `units` is the number of paid jobs started. It is never called for a request the API refused.
+
+File arguments and `-o` targets go through the Mirage VFS bridge (`globalThis.__MIRAGE_CLI_FILE_IO__`) when one is installed and claims the path, and otherwise through `node:fs`. For a Mirage mount, use [`@mirage-cli/contentdynamite`](../contentdynamite), which does all of this.
+
+## Where the source lives
+
+The CLI is developed next to the API in the Content Dynamite backend repository, which is private, and imports the API's own request schemas and response types so it cannot drift from it. `src/` here is generated from that repository by `bun run cli:mirage --out <this folder>`: the CLI files are copied as they are, the schemas and status helpers it uses are bundled into `src/wire.js`, and their types are written out flat to `src/wire.d.ts`. `src/source.json` names the commit it came from. Change the CLI there and regenerate, rather than editing `src/` by hand.

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/bin.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import {
+  run
+} from "./index-b00ea6js.js";
+
+// src/bin.ts
+process.exitCode = await run(process.argv.slice(2));

package/dist/client.d.ts

@@ -0,0 +1,24 @@
+export type Params = Record<string, string | number | boolean | null | undefined>;
+export declare class ApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export declare class ApiClient {
+    readonly baseUrl: string;
+    readonly token: string;
+    constructor(baseUrl: string, token: string);
+    get<T = unknown>(path: string, params?: Params): Promise<T>;
+    getText(path: string, params?: Params): Promise<string>;
+    getDownload(path: string, params?: Params): Promise<{
+        content: Uint8Array;
+        filename: string | null;
+    }>;
+    post<T = unknown>(path: string, body?: unknown, params?: Params): Promise<T>;
+    postForm<T = unknown>(path: string, file: Blob, filename: string, params?: Params): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown): Promise<T>;
+    delete<T = unknown>(path: string): Promise<T>;
+    private json;
+    private request;
+    private url;
+}

package/dist/commands/articles.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from 'commander';
+import type { ApiClient, Params } from '../client.js';
+import type { Cli } from '../context.js';
+import { type ArticleDoneRes, type ArticlePendingRes } from '../wire.js';
+export type ArticleRes = ArticleDoneRes | ArticlePendingRes;
+export declare function everyArticle(client: ApiClient, filter: Params): Promise<ArticleRes[]>;
+export declare function registerArticles(program: Command, cli: Cli): Command;

package/dist/commands/auth.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from 'commander';
+import { ApiClient } from '../client.js';
+import type { Cli } from '../context.js';
+import type { UserRes } from '../wire.js';
+export declare function signedIn(client: ApiClient, rejected: string): Promise<UserRes>;
+export declare function registerAuth(program: Command, cli: Cli): void;

package/dist/commands/batches.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { Cli } from '../context.js';
+export declare function registerBatches(program: Command, cli: Cli): void;

package/dist/commands/evals.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { Cli } from '../context.js';
+export declare function registerEvals(program: Command, cli: Cli): void;

package/dist/commands/gbp.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { Cli } from '../context.js';
+export declare function registerGbp(program: Command, cli: Cli): void;

package/dist/commands/images.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from 'commander';
+import type { ApiClient } from '../client.js';
+import type { Cli } from '../context.js';
+import type { EditFeatImageJobRes } from '../wire.js';
+export declare function loadJobCache(): Record<string, EditFeatImageJobRes>;
+export declare function cacheJob(key: string, job: EditFeatImageJobRes): void;
+export declare function fetchStatus(client: ApiClient, articleId: number, jobId: string, cached?: boolean): Promise<EditFeatImageJobRes>;
+export declare function registerImages(program: Command, cli: Cli): void;
+export declare function registerUpload(program: Command, cli: Cli): void;

package/dist/commands/landing-pages.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from 'commander';
+import type { Cli } from '../context.js';
+export declare function registerLandingPages(program: Command, cli: Cli): void;

package/dist/commands/profiles.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from 'commander';
+import type { Cli } from '../context.js';
+export declare function parseIcp(icp: string): Record<string, unknown> | null;
+export declare function registerProfiles(program: Command, cli: Cli): void;

package/dist/commands/revisions.d.ts

@@ -0,0 +1,4 @@
+import { type Command } from 'commander';
+import type { Cli } from '../context.js';
+export declare function registerArticleRevisions(articles: Command, cli: Cli): void;
+export declare function registerRevisions(program: Command, cli: Cli): void;

package/dist/commands/tokens.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { Cli } from '../context.js';
+export declare function registerTokens(program: Command, cli: Cli): void;

package/dist/commands/users.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from 'commander';
+import type { Cli } from '../context.js';
+export declare function registerUsers(program: Command, cli: Cli): void;

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+export declare const DEFAULT_API_URL = "https://content-dynamite.alexthecomputer1.workers.dev";
+export declare function configDir(): string;
+export declare const credentialsPath: () => string;
+export declare const imageJobsPath: () => string;
+export declare function defaultApiUrl(): string;
+export declare function envToken(): string | undefined;

package/dist/context.d.ts

@@ -0,0 +1,13 @@
+import type { Command } from 'commander';
+import { ApiClient } from './client.js';
+import { type ResolvedToken } from './credentials.js';
+import type { ProgramOptions } from './options.js';
+export interface Cli {
+    mount: boolean;
+    baseUrl(): string;
+    token(): ResolvedToken;
+    client(): ApiClient;
+    follow(watch: string, get: string): string;
+    billed(units: number): void;
+}
+export declare function cliFor(program: Command, { mount, reportCost }: ProgramOptions): Cli;

package/dist/credentials.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+export declare const PAT_PREFIX = "ved_";
+declare const storedCredentials: z.ZodObject<{
+    authToken: z.ZodString;
+    email: z.ZodString;
+    username: z.ZodString;
+    profile: z.ZodNullable<z.ZodString>;
+    expiresAt: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type StoredCredentials = z.output<typeof storedCredentials>;
+export interface ResolvedToken {
+    token: string;
+    source: 'flag' | 'env' | 'stored';
+    credentials: StoredCredentials | null;
+}
+export declare const isPat: (token: string) => boolean;
+export declare function loadCredentials(): StoredCredentials | null;
+export declare function saveCredentials({ authToken, email, username, profile, expiresAt }: StoredCredentials): void;
+export declare function clearCredentials(): void;
+export declare function decodeJwtPayload(token: string): Record<string, unknown> | null;
+export declare function decodeJwtExp(token: string): number | null;
+export declare function resolveToken(flagToken?: string, stored?: boolean): ResolvedToken;
+export {};

package/dist/files.d.ts

@@ -0,0 +1,3 @@
+export declare function readBytes(path: string): Uint8Array<ArrayBuffer>;
+export declare const readText: (path: string) => string;
+export declare function writeFile(path: string, data: string | Uint8Array): void;

package/dist/helpers.d.ts

@@ -0,0 +1,27 @@
+import { type Command, CommanderError } from 'commander';
+import type { Cli } from './context.js';
+export declare class Exit extends CommanderError {
+    constructor(code: number);
+}
+export declare const clock: {
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+};
+export declare const fmtNum: (value: number) => string;
+export declare const splitCsv: (value: string) => string[];
+export declare function integer(value: string): number;
+export declare function decimal(value: string): number;
+export declare function between(low: number, high: number): (value: string) => number;
+export declare function either(value: string | undefined, file: string | undefined, flags: string): string | undefined;
+export declare function documentOutput(command: Command, cli: Cli): Command;
+export declare function downloadDocument(cli: Cli, path: string, format: string, output: string | undefined, fallback: string): Promise<string>;
+export declare function interactiveFields(value: string | boolean | undefined): Record<string, string | boolean>;
+export interface Watch<T> {
+    interval: number;
+    timeout?: number;
+    poll: () => Promise<T>;
+    progress: (item: T) => string;
+    done: (item: T) => boolean;
+    timedOut: (item: T) => string;
+}
+export declare function watchLoop<T>({ interval, timeout, poll, progress, done, timedOut }: Watch<T>): Promise<T>;