steadylog 0.1.0

package/README.md

@@ -0,0 +1,26 @@
+# steadylog
+
+Connect a GitHub repo and set up [Steadylog](https://steadylog-phi.vercel.app) changelogs from your terminal.
+
+## Usage
+
+```bash
+npx steadylog init
+```
+
+This will:
+
+1. Authenticate with GitHub
+2. Connect your repo and register a webhook
+3. Add AI agent rule files (Cursor, Claude Code, Codex, or Windsurf)
+4. Create a `STEADYLOG.md` config in your repo
+
+## Local development
+
+```bash
+STEADYLOG_APP_URL=http://localhost:3000 npx steadylog init
+```
+
+## License
+
+MIT

package/dist/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function init(): Promise<void>;

package/dist/commands/init.js

@@ -0,0 +1,45 @@
+import chalk from "chalk";
+import inquirer from "inquirer";
+import ora from "ora";
+import { authenticate } from "../lib/auth.js";
+import { connectRepo, listRepos } from "../lib/api.js";
+import { detectAgent } from "../lib/detect.js";
+import { createConfig, placeRuleFile } from "../lib/files.js";
+export async function init() {
+    console.log(chalk.green("\n  Welcome to Steadylog 🪵\n"));
+    const spinner = ora();
+    spinner.start("Authenticating with GitHub...");
+    const token = await authenticate();
+    spinner.succeed(`Authenticated as @${token.github_username}`);
+    const repos = await listRepos(token);
+    const { repo } = await inquirer.prompt([
+        {
+            type: "list",
+            name: "repo",
+            message: "Which repo is this for?",
+            choices: repos.map((r) => ({ name: r.full_name, value: r })),
+        },
+    ]);
+    spinner.start("Connecting repo...");
+    const project = await connectRepo(token, repo);
+    spinner.succeed(`Repo connected — ${project.slug}`);
+    const agent = await detectAgent();
+    if (agent) {
+        spinner.start(`Setting up ${agent.name} integration...`);
+        await placeRuleFile(agent);
+        spinner.succeed(`Added Steadylog rules to ${agent.ruleFilePath}`);
+    }
+    await createConfig({
+        slug: project.slug,
+        repo: repo.full_name,
+    });
+    spinner.succeed("Created STEADYLOG.md");
+    console.log(`
+  ✅ You're all set.
+
+  Your changelog: ${chalk.green(project.changelog_url)}
+
+  Push your next release tag to ship your first changelog.
+  Your AI agent will handle the rest.
+  `);
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { init } from "./commands/init.js";
+const program = new Command();
+program
+    .name("steadylog")
+    .description("Automated changelogs from GitHub releases")
+    .version("0.1.0");
+program
+    .command("init")
+    .description("Connect a repo and set up Steadylog in your project")
+    .action(init);
+program.parse();

package/dist/lib/api.d.ts

@@ -0,0 +1,13 @@
+import type { SteadylogToken } from "./auth.js";
+export type GitHubRepo = {
+    id: number;
+    full_name: string;
+    name: string;
+    private: boolean;
+};
+export type ConnectedProject = {
+    slug: string;
+    changelog_url: string;
+};
+export declare function listRepos(token: SteadylogToken): Promise<GitHubRepo[]>;
+export declare function connectRepo(token: SteadylogToken, repo: GitHubRepo): Promise<ConnectedProject>;

package/dist/lib/api.js

@@ -0,0 +1,20 @@
+import axios from "axios";
+import { getApiUrl } from "./config.js";
+function authHeaders(token) {
+    return {
+        Authorization: `Bearer ${token.access_token}`,
+    };
+}
+export async function listRepos(token) {
+    const { data } = await axios.get(`${getApiUrl()}/api/cli/repos`, {
+        headers: authHeaders(token),
+    });
+    return data;
+}
+export async function connectRepo(token, repo) {
+    const { data } = await axios.post(`${getApiUrl()}/api/cli/connect`, {
+        repo_full_name: repo.full_name,
+        github_repo_id: repo.id,
+    }, { headers: authHeaders(token) });
+    return data;
+}

package/dist/lib/auth.d.ts

@@ -0,0 +1,7 @@
+export type SteadylogToken = {
+    access_token: string;
+    github_username: string;
+};
+export type StoredConfig = SteadylogToken;
+export declare function loadConfig(): Promise<StoredConfig | null>;
+export declare function authenticate(): Promise<SteadylogToken>;

package/dist/lib/auth.js

@@ -0,0 +1,127 @@
+import crypto from "node:crypto";
+import http from "node:http";
+import { URL } from "node:url";
+import axios from "axios";
+import fs from "fs-extra";
+import open from "open";
+import path from "node:path";
+import os from "node:os";
+import { getApiUrl, getAppUrl } from "./config.js";
+const DEFAULT_CALLBACK_PORT = 9898;
+const CALLBACK_PORT_ATTEMPTS = 10;
+const CALLBACK_TIMEOUT_MS = 10 * 60 * 1000;
+const CONFIG_DIR = path.join(os.homedir(), ".steadylog");
+const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
+function generateRandomString(length) {
+    return crypto.randomBytes(length).toString("base64url");
+}
+function generateCodeChallenge(verifier) {
+    return crypto.createHash("sha256").update(verifier).digest("base64url");
+}
+async function saveConfig(token) {
+    await fs.ensureDir(CONFIG_DIR);
+    await fs.writeJson(CONFIG_PATH, token, { spaces: 2 });
+}
+export async function loadConfig() {
+    if (!(await fs.pathExists(CONFIG_PATH))) {
+        return null;
+    }
+    return fs.readJson(CONFIG_PATH);
+}
+function listenForCallback(port, state) {
+    return new Promise((resolve, reject) => {
+        const server = http.createServer((req, res) => {
+            if (!req.url?.startsWith("/callback")) {
+                res.writeHead(404);
+                res.end();
+                return;
+            }
+            const url = new URL(req.url, `http://localhost:${port}`);
+            const code = url.searchParams.get("code");
+            const returnedState = url.searchParams.get("state");
+            if (!code || !returnedState) {
+                res.writeHead(400, { "Content-Type": "text/html" });
+                res.end("<h1>Missing code or state</h1>");
+                cleanup(new Error("OAuth callback missing code or state"));
+                return;
+            }
+            if (returnedState !== state) {
+                res.writeHead(400, { "Content-Type": "text/html" });
+                res.end("<h1>State mismatch</h1>");
+                cleanup(new Error("OAuth state mismatch"));
+                return;
+            }
+            res.writeHead(200, { "Content-Type": "text/html" });
+            res.end("<h1>Authenticated!</h1><p>You can close this tab and return to the terminal.</p>");
+            cleanup(null, { code, state: returnedState });
+        });
+        const timeout = setTimeout(() => {
+            cleanup(new Error("Timed out waiting for GitHub authentication"));
+        }, CALLBACK_TIMEOUT_MS);
+        function cleanup(error, result) {
+            clearTimeout(timeout);
+            server.close(() => {
+                if (error) {
+                    reject(error);
+                }
+                else if (result) {
+                    resolve(result);
+                }
+            });
+        }
+        server.on("error", (error) => {
+            clearTimeout(timeout);
+            if (error.code === "EADDRINUSE") {
+                reject(new Error(`Port ${port} is already in use. Kill the stale process with: lsof -ti :${port} | xargs kill`));
+                return;
+            }
+            reject(error);
+        });
+        server.listen(port, "127.0.0.1");
+    });
+}
+async function findAvailableCallbackPort() {
+    const envPort = process.env.STEADYLOG_CALLBACK_PORT;
+    if (envPort) {
+        return Number(envPort);
+    }
+    for (let i = 0; i < CALLBACK_PORT_ATTEMPTS; i++) {
+        const port = DEFAULT_CALLBACK_PORT + i;
+        try {
+            await new Promise((resolve, reject) => {
+                const probe = http.createServer();
+                probe.once("error", reject);
+                probe.listen(port, "127.0.0.1", () => {
+                    probe.close((err) => (err ? reject(err) : resolve()));
+                });
+            });
+            return port;
+        }
+        catch (error) {
+            const err = error;
+            if (err.code !== "EADDRINUSE") {
+                throw error;
+            }
+        }
+    }
+    throw new Error(`No available callback port (${DEFAULT_CALLBACK_PORT}-${DEFAULT_CALLBACK_PORT + CALLBACK_PORT_ATTEMPTS - 1}). Kill stale processes with: lsof -i :${DEFAULT_CALLBACK_PORT}`);
+}
+export async function authenticate() {
+    const state = generateRandomString(32);
+    const codeVerifier = generateRandomString(64);
+    const codeChallenge = generateCodeChallenge(codeVerifier);
+    const callbackPort = await findAvailableCallbackPort();
+    const authUrl = new URL(`${getAppUrl()}/cli-auth`);
+    authUrl.searchParams.set("state", state);
+    authUrl.searchParams.set("code_challenge", codeChallenge);
+    authUrl.searchParams.set("callback_port", String(callbackPort));
+    const callbackPromise = listenForCallback(callbackPort, state);
+    await open(authUrl.toString());
+    const { code } = await callbackPromise;
+    const { data } = await axios.post(`${getApiUrl()}/api/cli/token`, {
+        code,
+        code_verifier: codeVerifier,
+    });
+    await saveConfig(data);
+    return data;
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,2 @@
+export declare function getAppUrl(): string;
+export declare function getApiUrl(): string;

package/dist/lib/config.js

@@ -0,0 +1,10 @@
+function trimTrailingSlash(url) {
+    return url.replace(/\/$/, "");
+}
+const PRODUCTION_APP_URL = "https://steadylog-phi.vercel.app";
+export function getAppUrl() {
+    return trimTrailingSlash(process.env.STEADYLOG_APP_URL ?? PRODUCTION_APP_URL);
+}
+export function getApiUrl() {
+    return trimTrailingSlash(process.env.STEADYLOG_API_URL ?? getAppUrl());
+}

package/dist/lib/detect.d.ts

@@ -0,0 +1,6 @@
+export type Agent = {
+    name: string;
+    ruleFilePath: string;
+    templateFile: string;
+};
+export declare function detectAgent(): Promise<Agent | null>;

package/dist/lib/detect.js

@@ -0,0 +1,50 @@
+import fs from "fs-extra";
+import inquirer from "inquirer";
+const AGENT_CHOICES = {
+    Cursor: {
+        name: "Cursor",
+        ruleFilePath: ".cursor/rules/steadylog.mdc",
+        templateFile: "steadylog.mdc",
+    },
+    "Claude Code": {
+        name: "Claude Code",
+        ruleFilePath: "CLAUDE.md",
+        templateFile: "steadylog-claude.md",
+    },
+    Codex: {
+        name: "Codex",
+        ruleFilePath: "AGENTS.md",
+        templateFile: "steadylog-codex.md",
+    },
+    Windsurf: {
+        name: "Windsurf",
+        ruleFilePath: ".windsurfcontext",
+        templateFile: "steadylog-claude.md",
+    },
+};
+export async function detectAgent() {
+    if (await fs.pathExists(".cursor")) {
+        return AGENT_CHOICES.Cursor;
+    }
+    if (await fs.pathExists("CLAUDE.md")) {
+        return AGENT_CHOICES["Claude Code"];
+    }
+    if (await fs.pathExists("AGENTS.md")) {
+        return AGENT_CHOICES.Codex;
+    }
+    if (await fs.pathExists(".windsurfcontext")) {
+        return AGENT_CHOICES.Windsurf;
+    }
+    const { agent } = await inquirer.prompt([
+        {
+            type: "list",
+            name: "agent",
+            message: "Which AI coding tool do you use?",
+            choices: ["Cursor", "Claude Code", "Codex", "Windsurf", "None / Skip"],
+        },
+    ]);
+    if (agent === "None / Skip") {
+        return null;
+    }
+    return AGENT_CHOICES[agent];
+}

package/dist/lib/files.d.ts

@@ -0,0 +1,6 @@
+import type { Agent } from "./detect.js";
+export declare function placeRuleFile(agent: Agent): Promise<void>;
+export declare function createConfig({ slug, repo, }: {
+    slug: string;
+    repo: string;
+}): Promise<void>;

package/dist/lib/files.js

@@ -0,0 +1,24 @@
+import fs from "fs-extra";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.join(__dirname, "..", "templates");
+function readTemplate(filename) {
+    return fs.readFileSync(path.join(TEMPLATES_DIR, filename), "utf-8");
+}
+export async function placeRuleFile(agent) {
+    const template = readTemplate(agent.templateFile);
+    if (agent.name === "Claude Code" || agent.name === "Codex") {
+        await fs.appendFile(agent.ruleFilePath, "\n\n" + template);
+    }
+    else {
+        await fs.ensureDir(path.dirname(agent.ruleFilePath));
+        await fs.writeFile(agent.ruleFilePath, template);
+    }
+}
+export async function createConfig({ slug, repo, }) {
+    const template = readTemplate("STEADYLOG.md")
+        .replace("{{slug}}", slug)
+        .replace("{{repo}}", repo);
+    await fs.writeFile("STEADYLOG.md", template);
+}

package/dist/templates/STEADYLOG.md

@@ -0,0 +1,39 @@
+# Steadylog config
+# Docs: https://steadylog.dev/docs/config
+
+project: {{slug}}
+repo: {{repo}}
+
+# How changelog entries are published
+# auto: publishes immediately on release
+# manual: sends email for one-click approval (recommended)
+publish: manual
+
+# What triggers a changelog generation
+# tag: when you push a git tag (v1.2.3)
+# weekly: every Monday, bundles the week's PRs
+release_trigger: tag
+
+# Writing tone for AI-generated entries
+# professional | casual | technical
+tone: professional
+
+# How your product is referred to in the changelog
+# product_name: Acme
+
+# Paths to always ignore (changes here never appear in changelog)
+ignore_paths:
+  - .github/
+  - tests/
+  - __tests__/
+  - "*.test.ts"
+  - "*.spec.ts"
+  - infrastructure/
+  - scripts/
+  - docs/
+
+# Slack webhook for notifications (optional)
+# slack_webhook: https://hooks.slack.com/services/...
+
+# Email to notify on new draft (defaults to GitHub account email)
+# notify_email: team@yourcompany.com

package/dist/templates/steadylog-claude.md

@@ -0,0 +1,23 @@
+## Steadylog (Changelog Automation)
+
+This repo uses Steadylog to auto-generate changelogs. Follow these rules.
+
+### PR labeling
+Add a `changelog` label to PRs that affect users:
+✅ New features, bug fixes users notice, perf improvements, API changes
+❌ Deps, refactors, CI, tests, infra, comments
+
+### PR description
+For changelog PRs, append to the PR body:
+```
+## Steadylog
+**Type:** feature | improvement | fix
+**Summary:** One sentence for users, not engineers.
+```
+
+### Releases
+Always use `v` prefix: `v1.2.3`
+After tagging: "Steadylog will generate your changelog — check email to approve."
+
+### Not set up yet?
+Run: npx steadylog init

package/dist/templates/steadylog-codex.md

@@ -0,0 +1,16 @@
+## Steadylog changelog rules
+
+Repo uses Steadylog (npx steadylog init to set up).
+
+PR labels:
+- Add `changelog` label if change affects end users
+- Skip for: deps, refactors, CI, tests, infra
+
+PR description (changelog PRs only):
+```
+## Steadylog
+**Type:** feature | improvement | fix
+**Summary:** <one user-facing sentence>
+```
+
+Releases: use semver with v prefix (v1.2.3). Steadylog auto-generates changelog on tag push.

package/dist/templates/steadylog.mdc

@@ -0,0 +1,71 @@
+---
+description: Steadylog changelog automation rules
+alwaysApply: true
+---
+
+# Steadylog
+
+This repo uses Steadylog (steadylog.dev) to automatically generate changelogs
+from GitHub releases. Follow these rules on every PR and release.
+
+## PR rules
+
+When creating or reviewing a PR, decide if the change is user-facing:
+
+USER-FACING (add `changelog` label):
+- New features or UI changes
+- Bug fixes that affected user experience
+- Performance improvements users will notice
+- New API endpoints or changed API behavior
+- Changes to pricing, limits, or permissions
+
+NOT USER-FACING (no label needed):
+- Dependency updates
+- Refactors with no behavior change
+- CI/CD changes
+- Test additions
+- Code comments or documentation
+- Infrastructure / DevOps changes
+- Internal tooling
+
+## PR description format
+
+For changelog-labeled PRs, always include this at the bottom of the PR description:
+
+```
+## Steadylog
+**Type:** feature | improvement | fix  (pick one)
+**Summary:** One sentence describing what changed from the user's perspective.
+```
+
+Example:
+```
+## Steadylog
+**Type:** feature
+**Summary:** Users can now export their dashboard data as a CSV file.
+```
+
+This helps Steadylog's AI write a better changelog entry.
+
+## Release rules
+
+When the developer asks you to cut a release or ship a version:
+
+1. Remind them to use semver format: `v1.2.3` (with the `v` prefix)
+2. Suggest the right version bump:
+   - New features → minor bump (v1.1.0 → v1.2.0)
+   - Bug fixes only → patch bump (v1.1.0 → v1.1.1)
+   - Breaking changes → major bump (v1.1.0 → v2.0.0)
+3. After tagging, remind them: "Steadylog will generate your changelog automatically. Check your email to approve it."
+
+## STEADYLOG.md
+
+This repo has a STEADYLOG.md config file. Respect its settings:
+- `ignore_paths` — never suggest changelog labels for PRs that only touch these paths
+- `tone` — match this tone when writing PR summaries
+- `release_trigger` — how releases are detected
+
+## Setup
+
+If Steadylog is not yet set up for this repo, tell the developer to run:
+npx steadylog init

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "steadylog",
+  "version": "0.1.0",
+  "description": "Automated changelogs from GitHub releases",
+  "type": "module",
+  "bin": {
+    "steadylog": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc && cp -r src/templates dist/templates",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/majamil16/steadylog.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/majamil16/steadylog/issues"
+  },
+  "homepage": "https://steadylog-phi.vercel.app",
+  "license": "MIT",
+  "keywords": [
+    "changelog",
+    "github",
+    "releases",
+    "cli",
+    "steadylog"
+  ],
+  "dependencies": {
+    "axios": "^1.0.0",
+    "chalk": "^5.0.0",
+    "commander": "^11.0.0",
+    "fs-extra": "^11.0.0",
+    "inquirer": "^9.0.0",
+    "open": "^9.0.0",
+    "ora": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.0",
+    "@types/inquirer": "^9.0.0",
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}