deploylog 0.3.0 → 0.4.0

package/README.md

@@ -38,54 +38,94 @@ Credentials are stored with [`conf`](https://github.com/sindresorhus/conf) in yo
 ## Quick start
 
 ```bash
-# List your projects
-deploylog projects
+# Wire this repo to a project (writes .deploylog.yml)
+deploylog init
 
-# Publish an entry
-deploylog push \
-  --project my-app \
-  --title "Dark mode" \
-  --body "Auto-detects system preference." \
-  --type feature \
-  --version 1.4.0 \
-  --publish
+# Draft an entry from your commits, rewritten by AI
+deploylog push --from-git --ai-summarize
+
+# Review it, then ship it
+deploylog list --drafts
+deploylog view dark-mode
+deploylog publish dark-mode
 ```
 
+The full lifecycle lives in the terminal: create, list, view, edit, publish, unpublish, delete. No dashboard detour.
+
 ## Project config
 
-Create a `.deploylog.yml` at your repo root so you don't have to pass `--project` every time:
+`deploylog init` writes a `.deploylog.yml` at your repo root so you don't have to pass `--project` every time:
 
 ```yaml
 project: my-app
+default_type: feature   # optional
+```
+
+## Referencing entries
+
+Entry commands accept a **slug or an id** (`deploylog publish dark-mode`, `deploylog publish 3f2b8a1c-...`). Slugs are matched against the 50 most recent entries; older entries need the id (`deploylog list` shows both). Note that editing a draft's title can change its slug, so scripts should prefer ids.
+
+## Machine-readable output
+
+Every data command takes `--json`: raw JSON on stdout, errors as `{"error":{"code","message"}}` on stderr, and no interactive prompts, ever. Built for CI and AI agents.
+
+```bash
+deploylog list --drafts --json | jq -r '.[0].id'
 ```
 
 ## Commands
 
-### `deploylog login`
+### `deploylog login` / `deploylog logout`
 
-Authenticate with an API key.
+Authenticate with an API key (create one at [deploylog.dev/dashboard/api-keys](https://deploylog.dev/dashboard/api-keys)).
 
 ```
 --key <key>       API key (starts with dk_)
 --api-url <url>   API base URL (default: https://deploylog.dev)
 ```
 
-### `deploylog logout`
+### `deploylog init`
 
-Remove stored credentials.
+Scaffold `.deploylog.yml` in the current directory. Picks the project interactively, or takes `--project`.
 
-### `deploylog projects`
+```
+-p, --project <slug>   Project slug
+-T, --type <type>      Default entry type for pushes from this repo
+--force                Overwrite an existing .deploylog.yml
+```
+
+### `deploylog projects` (alias: `proj`)
 
 List projects in your organization.
 
-### `deploylog list`
+### `deploylog projects create <name>`
+
+Create a project. The slug is generated from the name.
+
+```
+--url <url>   Project website URL
+```
+
+### `deploylog whoami`
+
+Show the authenticated org, plan, API key (name, prefix, permissions), and AI usage this month.
+
+### `deploylog list` (alias: `ls`)
 
-List recent entries for a project.
+List recent entries for a project. Prints each entry's slug and id.
 
 ```
 -p, --project <slug>   Project slug (or set in .deploylog.yml)
+--drafts               Only drafts
+--published            Only published entries
+-T, --type <type>      Filter by entry type
+-n, --limit <n>        Max entries (1-50)
 ```
 
+### `deploylog view <entry>` (alias: `show`)
+
+Show a full entry, including its Markdown body.
+
 ### `deploylog push`
 
 Create a new changelog entry.
@@ -103,31 +143,70 @@ Create a new changelog entry.
 -y, --yes                 Skip interactive confirmation for AI-generated content
 ```
 
+### `deploylog edit <entry>`
+
+Update an entry. With no field flags on an interactive terminal, your `$EDITOR` opens prefilled with the current body. If the server rejects an edited body, it is saved to a recovery file, never lost.
+
+```
+-t, --title <title>     New title (may change a draft's slug; the CLI tells you)
+-T, --type <type>       Entry type
+--version <version>     Semver version (pass "" to clear)
+-b, --body <markdown>   New body
+--body-file <path>      Read the new body from a file (- for stdin)
+```
+
+### `deploylog publish <entry>` (alias: `pub`) / `deploylog unpublish <entry>` (alias: `unpub`)
+
+Publish a draft, or revert a published entry to draft. Publishing is idempotent: re-running is a no-op, and the email digest (Pro) is sent at most once per entry, ever. Unpublishing resets the publish date; republishing gets a new one.
+
+### `deploylog delete <entry>` (alias: `rm`)
+
+Delete an entry permanently. Prompts for confirmation on a terminal; requires `--yes` in CI or `--json` mode.
+
+### `deploylog import github <repo>`
+
+Backfill your existing GitHub releases as draft entries. Takes `owner/repo` or a github.com URL. Skips versions you already imported.
+
+```
+-p, --project <slug>   Project slug (or set in .deploylog.yml)
+--token <token>        GitHub PAT for private repos / rate limits (or DEPLOYLOG_GITHUB_TOKEN); never stored
+```
+
+### `deploylog open [entry]` (alias: `o`)
+
+Open the project's public changelog (or one entry's page) in your browser. Prints the URL when headless.
+
 ## Recipes
 
-**Draft from recent commits:**
+**Onboard a repo in one minute:**
 
 ```bash
-deploylog push --from-git
+deploylog login --key dk_xxx
+deploylog projects create "My App" --url https://myapp.dev
+deploylog init
+deploylog import github me/my-app     # backfill old releases as drafts
+deploylog list --drafts               # review
+deploylog publish v1-4-0
 ```
 
-Collects commits since the last git tag, formats them as a Markdown list, and opens the entry as a draft.
-
-**AI-polished release notes:**
+**Draft from recent commits, ship after review:**
 
 ```bash
-deploylog push --from-git --ai-summarize --version 1.4.0 --publish
-# or, with short flags and the dpl alias:
-dpl push -g -a --version 1.4.0 --publish
+deploylog push --from-git --ai-summarize
+deploylog view <slug>        # read what the AI wrote
+deploylog edit <slug>        # tweak in $EDITOR
+deploylog publish <slug>
 ```
 
-Uses Claude Haiku to rewrite your raw commits into user-friendly release notes. Free plan includes 5 AI summaries per month; paid plans are unlimited.
+**CI: publish on release, no prompts:**
 
-**CI / GitHub Actions:**
+```bash
+deploylog push --from-git --ai-summarize --yes --publish --json
+```
 
-For CI workflows, prefer the official Action:
+For GitHub Actions specifically, prefer the official Action: [`deploylogdev/action`](https://github.com/marketplace/actions/publish-to-deploylog).
 
-- [`deploylogdev/action`](https://github.com/marketplace/actions/publish-to-deploylog) on the GitHub Marketplace
+**Agent-driven usage:** every command's `--json` output is stable and prompt-free; destructive operations refuse without an explicit `--yes`.
 
 ## Related
 

package/dist/api.d.ts

@@ -21,7 +21,55 @@ export interface Entry {
     created_at: string;
 }
 export declare function listProjects(): Promise<Project[]>;
-export declare function listEntries(projectSlug: string): Promise<Entry[]>;
+export declare function createProject(name: string, websiteUrl?: string): Promise<Project>;
+export interface GithubImportResult {
+    imported: number;
+    skipped: number;
+}
+export declare function importGithub(projectSlug: string, repo: string, token?: string): Promise<GithubImportResult>;
+export interface WhoAmI {
+    organization: {
+        name: string;
+        slug: string;
+        plan: string | null;
+    };
+    api_key: {
+        name: string;
+        prefix: string;
+        permissions: string[];
+        last_used_at: string | null;
+        created_at: string;
+    };
+    ai_usage: {
+        used: number;
+        limit: number | null;
+        month_key: string;
+    };
+}
+export declare function whoami(): Promise<WhoAmI>;
+export interface ListEntriesFilters {
+    status?: 'draft' | 'published';
+    type?: string;
+    limit?: number;
+}
+export declare function listEntries(projectSlug: string, filters?: ListEntriesFilters): Promise<Entry[]>;
+/** Full entry including the markdown body — the single-entry GET. */
+export interface EntryDetail extends Entry {
+    body_markdown: string;
+    updated_at: string | null;
+}
+export declare function getEntry(entryId: string): Promise<EntryDetail>;
+export interface UpdateEntryInput {
+    title?: string;
+    body_markdown?: string;
+    entry_type?: string | null;
+    version?: string;
+    slug?: string;
+}
+export declare function updateEntry(entryId: string, input: UpdateEntryInput): Promise<EntryDetail>;
+export declare function deleteEntry(entryId: string): Promise<{
+    id: string;
+}>;
 export interface CreateEntryInput {
     title: string;
     body_markdown: string;
@@ -30,6 +78,16 @@ export interface CreateEntryInput {
     publish?: boolean;
 }
 export declare function createEntry(projectSlug: string, input: CreateEntryInput): Promise<Entry>;
+/** Entry row returned by the publish route, plus whether the state actually changed. */
+export interface PublishStateEntry {
+    id: string;
+    title: string;
+    slug: string;
+    published: boolean;
+    published_at: string | null;
+    changed: boolean;
+}
+export declare function setEntryPublished(entryId: string, published: boolean): Promise<PublishStateEntry>;
 export interface SummarizeInput {
     project_slug?: string;
     commits?: string[];

package/dist/api.js

@@ -46,8 +46,43 @@ async function request(path, options = {}) {
 export async function listProjects() {
     return request('/projects');
 }
-export async function listEntries(projectSlug) {
-    return request(`/projects/${projectSlug}/entries`);
+export async function createProject(name, websiteUrl) {
+    return request('/projects', {
+        method: 'POST',
+        body: JSON.stringify({ name, website_url: websiteUrl ?? '' }),
+    });
+}
+export async function importGithub(projectSlug, repo, token) {
+    return request(`/projects/${projectSlug}/import/github`, {
+        method: 'POST',
+        body: JSON.stringify(token ? { repo, token } : { repo }),
+    });
+}
+export async function whoami() {
+    return request('/whoami');
+}
+export async function listEntries(projectSlug, filters = {}) {
+    const params = new URLSearchParams();
+    if (filters.status)
+        params.set('status', filters.status);
+    if (filters.type)
+        params.set('type', filters.type);
+    if (filters.limit !== undefined)
+        params.set('limit', String(filters.limit));
+    const qs = params.toString();
+    return request(`/projects/${projectSlug}/entries${qs ? `?${qs}` : ''}`);
+}
+export async function getEntry(entryId) {
+    return request(`/entries/${entryId}`);
+}
+export async function updateEntry(entryId, input) {
+    return request(`/entries/${entryId}`, {
+        method: 'PATCH',
+        body: JSON.stringify(input),
+    });
+}
+export async function deleteEntry(entryId) {
+    return request(`/entries/${entryId}`, { method: 'DELETE' });
 }
 export async function createEntry(projectSlug, input) {
     return request(`/projects/${projectSlug}/entries`, {
@@ -55,6 +90,12 @@ export async function createEntry(projectSlug, input) {
         body: JSON.stringify(input),
     });
 }
+export async function setEntryPublished(entryId, published) {
+    return request(`/entries/${entryId}/publish`, {
+        method: 'POST',
+        body: JSON.stringify({ published }),
+    });
+}
 export async function summarize(input) {
     return request('/ai-summarize', {
         method: 'POST',

package/dist/editor.d.ts

@@ -0,0 +1,23 @@
+export type EditorResult = {
+    kind: 'edited';
+    body: string;
+} | {
+    kind: 'unchanged';
+} | {
+    kind: 'aborted';
+    message: string;
+} | {
+    kind: 'no-editor';
+    message: string;
+};
+/**
+ * Round-trip a markdown body through $EDITOR (fallback: $VISUAL, then vi).
+ * Trailing newlines are normalized before the no-op check — editors append
+ * one on save, and that alone must not count as a change.
+ */
+export declare function editInEditor(initial: string): EditorResult;
+/**
+ * Persist a body the server rejected so the user's writing is never lost —
+ * printed in the error message as a recoverable path.
+ */
+export declare function saveRecoveryFile(body: string): string;

package/dist/editor.js

@@ -0,0 +1,46 @@
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, writeFileSync, rmSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Round-trip a markdown body through $EDITOR (fallback: $VISUAL, then vi).
+ * Trailing newlines are normalized before the no-op check — editors append
+ * one on save, and that alone must not count as a change.
+ */
+export function editInEditor(initial) {
+    const editor = process.env.EDITOR ?? process.env.VISUAL ?? 'vi';
+    const dir = mkdtempSync(join(tmpdir(), 'deploylog-'));
+    const file = join(dir, 'entry.md');
+    writeFileSync(file, initial, 'utf8');
+    try {
+        const res = spawnSync(editor, [file], { stdio: 'inherit' });
+        if (res.error) {
+            return {
+                kind: 'no-editor',
+                message: `Could not launch editor '${editor}'. Set $EDITOR, or pass --body / --body-file instead.`,
+            };
+        }
+        if (res.status !== 0) {
+            return { kind: 'aborted', message: `Editor exited with status ${res.status}; entry not changed.` };
+        }
+        const edited = readFileSync(file, 'utf8');
+        if (edited.replace(/\n+$/, '') === initial.replace(/\n+$/, '')) {
+            return { kind: 'unchanged' };
+        }
+        return { kind: 'edited', body: edited };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+/**
+ * Persist a body the server rejected so the user's writing is never lost —
+ * printed in the error message as a recoverable path.
+ */
+export function saveRecoveryFile(body) {
+    const dir = join(tmpdir(), 'deploylog-recovery');
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, `entry-${process.pid}-${Date.now()}.md`);
+    writeFileSync(file, body, 'utf8');
+    return file;
+}

package/dist/entry-commands.d.ts

@@ -0,0 +1,111 @@
+import { type Entry, type EntryDetail, type PublishStateEntry, type UpdateEntryInput } from './api.js';
+import { type ProjectConfig } from './project-config.js';
+import { type EditorResult } from './editor.js';
+/**
+ * Shared deps for the entry-lifecycle commands (publish/unpublish, and the
+ * view/edit/delete siblings that follow) — same DI shape as PushDeps.
+ */
+export interface EntryCommandDeps {
+    api: {
+        listEntries(slug: string): Promise<Entry[]>;
+        getEntry(id: string): Promise<EntryDetail>;
+        updateEntry(id: string, input: UpdateEntryInput): Promise<EntryDetail>;
+        deleteEntry(id: string): Promise<{
+            id: string;
+        }>;
+        setEntryPublished(id: string, published: boolean): Promise<PublishStateEntry>;
+    };
+    readProjectConfig(): ProjectConfig | null;
+    editor(initial: string): EditorResult;
+    saveRecovery(body: string): string;
+    readFile(path: string): string;
+    confirm(question: string): Promise<boolean>;
+    isTTY: boolean;
+}
+export interface SetPublishedOptions {
+    ref: string;
+    project?: string;
+    publish: boolean;
+}
+export type SetPublishedResult = {
+    kind: 'updated';
+    entry: PublishStateEntry;
+    publish: boolean;
+} | {
+    kind: 'not-found';
+    message: string;
+} | {
+    kind: 'missing-fields';
+    message: string;
+};
+export declare function runSetPublished(opts: SetPublishedOptions, deps?: EntryCommandDeps): Promise<SetPublishedResult>;
+export interface ViewOptions {
+    ref: string;
+    project?: string;
+}
+export type ViewResult = {
+    kind: 'found';
+    entry: EntryDetail;
+} | {
+    kind: 'not-found';
+    message: string;
+} | {
+    kind: 'missing-fields';
+    message: string;
+};
+export declare function runView(opts: ViewOptions, deps?: EntryCommandDeps): Promise<ViewResult>;
+export interface EditOptions {
+    ref: string;
+    project?: string;
+    title?: string;
+    type?: string;
+    version?: string;
+    body?: string;
+    bodyFile?: string;
+}
+export type EditResult = {
+    kind: 'updated';
+    entry: EntryDetail;
+    previousSlug: string;
+} | {
+    kind: 'not-found';
+    message: string;
+} | {
+    kind: 'missing-fields';
+    message: string;
+} | {
+    kind: 'cancelled';
+    message: string;
+} | {
+    kind: 'unchanged';
+    message: string;
+} | {
+    kind: 'body-rejected';
+    message: string;
+    recoveryPath: string;
+};
+export declare function runEdit(opts: EditOptions, deps?: EntryCommandDeps): Promise<EditResult>;
+export interface DeleteOptions {
+    ref: string;
+    project?: string;
+    yes?: boolean;
+}
+export type DeleteResult = {
+    kind: 'deleted';
+    id: string;
+    title: string;
+} | {
+    kind: 'cancelled';
+    message: string;
+} | {
+    kind: 'confirm-required';
+    message: string;
+} | {
+    kind: 'not-found';
+    message: string;
+} | {
+    kind: 'missing-fields';
+    message: string;
+};
+export declare function runDelete(opts: DeleteOptions, deps?: EntryCommandDeps): Promise<DeleteResult>;
+export declare const defaultEntryCommandDeps: EntryCommandDeps;

package/dist/entry-commands.js

@@ -0,0 +1,157 @@
+import { readFileSync } from 'node:fs';
+import { listEntries, getEntry, updateEntry, deleteEntry, setEntryPublished, ApiError, } from './api.js';
+import { readProjectConfig } from './project-config.js';
+import { resolveEntryRef } from './resolve.js';
+import { editInEditor, saveRecoveryFile } from './editor.js';
+import { defaultPushDeps } from './push.js';
+export async function runSetPublished(opts, deps = defaultEntryCommandDeps) {
+    const projectConfig = deps.readProjectConfig();
+    const slug = opts.project ?? projectConfig?.project;
+    if (!slug) {
+        return {
+            kind: 'missing-fields',
+            message: 'No project specified. Use --project <slug> or create a .deploylog.yml with:\n  project: my-app',
+        };
+    }
+    const resolved = await resolveEntryRef(opts.ref, slug, deps.api.listEntries);
+    if (resolved.kind === 'not-found') {
+        return { kind: 'not-found', message: resolved.message };
+    }
+    const entry = await deps.api.setEntryPublished(resolved.id, opts.publish);
+    return { kind: 'updated', entry, publish: opts.publish };
+}
+export async function runView(opts, deps = defaultEntryCommandDeps) {
+    const projectConfig = deps.readProjectConfig();
+    const slug = opts.project ?? projectConfig?.project;
+    if (!slug) {
+        return {
+            kind: 'missing-fields',
+            message: 'No project specified. Use --project <slug> or create a .deploylog.yml with:\n  project: my-app',
+        };
+    }
+    const resolved = await resolveEntryRef(opts.ref, slug, deps.api.listEntries);
+    if (resolved.kind === 'not-found') {
+        return { kind: 'not-found', message: resolved.message };
+    }
+    const entry = await deps.api.getEntry(resolved.id);
+    return { kind: 'found', entry };
+}
+export async function runEdit(opts, deps = defaultEntryCommandDeps) {
+    const projectConfig = deps.readProjectConfig();
+    const slug = opts.project ?? projectConfig?.project;
+    if (!slug) {
+        return {
+            kind: 'missing-fields',
+            message: 'No project specified. Use --project <slug> or create a .deploylog.yml with:\n  project: my-app',
+        };
+    }
+    const resolved = await resolveEntryRef(opts.ref, slug, deps.api.listEntries);
+    if (resolved.kind === 'not-found') {
+        return { kind: 'not-found', message: resolved.message };
+    }
+    const current = await deps.api.getEntry(resolved.id);
+    const hasFieldFlags = opts.title !== undefined ||
+        opts.type !== undefined ||
+        opts.version !== undefined ||
+        opts.body !== undefined ||
+        opts.bodyFile !== undefined;
+    let body = opts.body;
+    let bodyFromEditor = false;
+    if (opts.bodyFile !== undefined && body === undefined) {
+        try {
+            body = deps.readFile(opts.bodyFile);
+        }
+        catch {
+            return { kind: 'missing-fields', message: `Could not read body file '${opts.bodyFile}'.` };
+        }
+    }
+    if (!hasFieldFlags) {
+        if (!deps.isTTY) {
+            return {
+                kind: 'missing-fields',
+                message: 'Nothing to edit. Pass --title / --type / --version / --body / --body-file (the $EDITOR flow needs an interactive terminal).',
+            };
+        }
+        const edited = deps.editor(current.body_markdown);
+        switch (edited.kind) {
+            case 'unchanged':
+                return { kind: 'unchanged', message: 'No changes made; entry left as is.' };
+            case 'aborted':
+                return { kind: 'cancelled', message: edited.message };
+            case 'no-editor':
+                return { kind: 'missing-fields', message: edited.message };
+            case 'edited':
+                body = edited.body;
+                bodyFromEditor = true;
+        }
+    }
+    const input = {};
+    if (opts.title !== undefined)
+        input.title = opts.title;
+    if (opts.type !== undefined)
+        input.entry_type = opts.type;
+    if (opts.version !== undefined)
+        input.version = opts.version;
+    if (body !== undefined)
+        input.body_markdown = body;
+    try {
+        const entry = await deps.api.updateEntry(resolved.id, input);
+        return { kind: 'updated', entry, previousSlug: current.slug };
+    }
+    catch (err) {
+        // A rejected editor-authored body must never be discarded — park it on
+        // disk and point at it.
+        if (bodyFromEditor && err instanceof ApiError && body !== undefined) {
+            const recoveryPath = deps.saveRecovery(body);
+            return {
+                kind: 'body-rejected',
+                message: `${err.message}\nYour edited body was saved to ${recoveryPath}`,
+                recoveryPath,
+            };
+        }
+        throw err;
+    }
+}
+export async function runDelete(opts, deps = defaultEntryCommandDeps) {
+    const projectConfig = deps.readProjectConfig();
+    const slug = opts.project ?? projectConfig?.project;
+    if (!slug) {
+        return {
+            kind: 'missing-fields',
+            message: 'No project specified. Use --project <slug> or create a .deploylog.yml with:\n  project: my-app',
+        };
+    }
+    const resolved = await resolveEntryRef(opts.ref, slug, deps.api.listEntries);
+    if (resolved.kind === 'not-found') {
+        return { kind: 'not-found', message: resolved.message };
+    }
+    // Fetch first so the confirm prompt names what's about to be destroyed
+    // (and so a wrong-org/missing id 404s before any prompt).
+    const entry = await deps.api.getEntry(resolved.id);
+    if (!opts.yes) {
+        // Deleting is permanent — stricter than push: a non-interactive shell
+        // must opt in explicitly instead of auto-proceeding.
+        if (!deps.isTTY) {
+            return {
+                kind: 'confirm-required',
+                message: 'Refusing to delete without confirmation. Pass --yes in non-interactive mode.',
+            };
+        }
+        const ok = await deps.confirm(`Delete '${entry.title}' (${entry.slug})? This is permanent.`);
+        if (!ok) {
+            return { kind: 'cancelled', message: 'Cancelled. Entry not deleted.' };
+        }
+    }
+    await deps.api.deleteEntry(resolved.id);
+    return { kind: 'deleted', id: resolved.id, title: entry.title };
+}
+export const defaultEntryCommandDeps = {
+    api: { listEntries, getEntry, updateEntry, deleteEntry, setEntryPublished },
+    readProjectConfig: () => readProjectConfig(),
+    editor: editInEditor,
+    saveRecovery: saveRecoveryFile,
+    // '-' reads stdin so agents/CI can pipe a body without a temp file.
+    readFile: (path) => readFileSync(path === '-' ? 0 : path, 'utf8'),
+    confirm: (question) => defaultPushDeps.confirm(question),
+    isTTY: Boolean(process.stdin.isTTY),
+};