apisteady 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miguel Gasang
+
+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,55 @@
-# Temporary Holding Version
+# apisteady
 
-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.
+**Generate typed TypeScript API clients from OpenAPI, and keep them maintainable as the API evolves.**
+
+apisteady turns an OpenAPI 3.0 / 3.1 or Swagger 2.0 spec into a dependency-free, fully typed TypeScript
+client. Then it keeps that client maintainable: regenerating never overwrites your code, names stay stable when
+the spec shifts, and every API change is listed, with breaking ones marked.
+
+```bash
+npm install --save-dev apisteady
+npx apisteady init        # writes .apisteadyrc.yml, detecting your openapi.yaml / .json
+npx apisteady generate    # writes ./sdk
+```
+
+```ts
+import { PetstoreClient } from './sdk/index.js';
+
+const client = new PetstoreClient({ auth: { bearerAuth: process.env.TOKEN } });
+const pets = await client.pets.listPets({ limit: 20, status: ['available'] });
+```
+
+## What it does
+
+- **Safe regeneration.** `generated/` is rewritten on every run. Your own code lives in `client.ts` (created once,
+  then yours) or in `// <apisteady:custom>` regions inside generated files, and is carried over. Hand edits to
+  generated code are detected instead of silently overwritten.
+- **Stable names.** Every assigned name is recorded in a lock file, so a renamed `operationId` or a new
+  colliding endpoint never renames an existing method.
+- **API changelog.** `apisteady diff` and `apisteady changelog` list what changed between two versions of the
+  spec, and mark breaking changes, judged by whether the data is sent or received.
+- **CI gating.** `apisteady generate --check` fails when the committed SDK is stale, and
+  `apisteady diff --base origin/main --require-bump` fails on breaking changes without a new major version.
+  A [GitHub Action](https://github.com/euruuuuu/steadysdk#github-action) runs both.
+- **Watch mode.** `apisteady watch` regenerates on every save of the spec, or of any file it references.
+- **Configurable naming, ignore lists, your own HTTP runtime** (`apisteady eject runtime`), and webhook payload types.
+
+## Commands
+
+| Command | |
+| --- | --- |
+| `apisteady init` | Create `.apisteadyrc.yml` |
+| `apisteady generate` | Generate the SDK (`--dry-run`, `--check`, `--relock`, `--force`) |
+| `apisteady watch` | Regenerate on every change |
+| `apisteady diff [old] [new]` | List API changes (`--base <git-rev>`, `--json`, `--fail-on-breaking`, `--require-bump`) |
+| `apisteady changelog [old] [new]` | Write the changes as Markdown or JSON (`--out <file>`) |
+| `apisteady eject runtime` | Copy the HTTP runtime into your project to customize it |
+
+The CLI needs Node.js 22.19 or newer. The generated SDK has no dependencies and runs anywhere `fetch` exists:
+Node.js 18+, browsers, Deno and Bun.
+
+**Documentation, examples and the full option reference:** <https://github.com/euruuuuu/steadysdk>
+
+## License
+
+MIT

package/dist/changes.d.ts

@@ -0,0 +1,13 @@
+import { type ApiDiff } from '@apisteady/core';
+import type { Ui } from './ui.js';
+export interface PrintChangesOptions {
+    /** Shown before the counts, e.g. `API changes since the last generation`. */
+    heading: string;
+    /** Maximum number of changes listed (breaking ones first); the rest are counted. */
+    limit?: number;
+    /** Shown when `limit` cuts the list short. */
+    moreHint?: string;
+}
+/** Terminal view of a diff: a summary line, then one line per change, breaking changes first. */
+export declare function printChanges(ui: Ui, diff: ApiDiff, options: PrintChangesOptions): void;
+//# sourceMappingURL=changes.d.ts.map

package/dist/changes.js

@@ -0,0 +1,32 @@
+import { changeSubject } from '@apisteady/core';
+/** Terminal view of a diff: a summary line, then one line per change, breaking changes first. */
+export function printChanges(ui, diff, options) {
+    const { breaking, nonBreaking } = diff.summary;
+    const counts = [
+        breaking > 0 ? ui.c.red(ui.c.bold(`${breaking} breaking`)) : undefined,
+        nonBreaking > 0 ? `${nonBreaking} non-breaking` : undefined,
+    ].filter(Boolean);
+    ui.info(`${options.heading}: ${counts.join(', ')}`);
+    const ordered = [...diff.changes.filter((change) => change.breaking), ...diff.changes.filter((change) => !change.breaking)];
+    const limit = options.limit ?? Number.POSITIVE_INFINITY;
+    for (const change of ordered.slice(0, limit)) {
+        ui.line(`    ${symbol(ui, change)} ${ui.c.bold(changeSubject(change))}: ${inlineCode(ui, change.message)}`);
+    }
+    if (ordered.length > limit) {
+        ui.line(ui.c.dim(`    … ${ordered.length - limit} more${options.moreHint ? ` (${options.moreHint})` : ''}`));
+    }
+}
+function symbol(ui, change) {
+    if (change.breaking)
+        return ui.c.red('!');
+    if (change.kind.endsWith('-added'))
+        return ui.c.green('+');
+    if (change.kind.endsWith('-removed'))
+        return ui.c.yellow('-');
+    return ui.c.yellow('~');
+}
+/** `code` spans become colored text on a color terminal and stay as backticks otherwise. */
+function inlineCode(ui, text) {
+    return ui.io.color ? text.replace(/`([^`]+)`/g, (_match, inner) => ui.c.cyan(inner)) : text;
+}
+//# sourceMappingURL=changes.js.map

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+import { type Io } from './ui.js';
+/** Runs the CLI in-process and resolves to the exit code. */
+export declare function run(argv: readonly string[], io?: Io): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -0,0 +1,107 @@
+import path from 'node:path';
+import { Argument, Command, CommanderError } from 'commander';
+import { APISTEADY_VERSION, TEMPLATE_NAMES } from '@apisteady/core';
+import { changelogCommand } from './commands/changelog.js';
+import { diffCommand } from './commands/diff.js';
+import { ejectCommand } from './commands/eject.js';
+import { generateCommand } from './commands/generate.js';
+import { watchCommand } from './commands/watch.js';
+import { initCommand } from './commands/init.js';
+import { defaultIo, Ui } from './ui.js';
+/** Runs the CLI in-process and resolves to the exit code. */
+export async function run(argv, io = defaultIo()) {
+    let exitCode = 0;
+    const program = new Command('apisteady')
+        .description('Generate and maintain typed API client SDKs from OpenAPI specs')
+        .version(APISTEADY_VERSION, '-v, --version')
+        .option('-C, --cwd <dir>', 'run as if started in <dir>')
+        .option('--no-color', 'disable colored output')
+        .showHelpAfterError()
+        .exitOverride()
+        .configureOutput({ writeOut: io.stdout, writeErr: io.stderr });
+    const uiFor = (command) => {
+        const globals = command.optsWithGlobals();
+        const cwd = globals.cwd === undefined ? io.cwd : path.resolve(io.cwd, globals.cwd);
+        return new Ui({ ...io, cwd, color: io.color && globals.color !== false });
+    };
+    // Commander calls actions with the positional arguments, then the options, then the command.
+    const action = (handler) => async (...received) => {
+        const command = received.at(-1);
+        const ui = uiFor(command);
+        try {
+            exitCode = await handler(ui, received.at(-2), command.processedArgs);
+        }
+        catch (error) {
+            ui.error(error);
+            exitCode = 1;
+        }
+    };
+    program
+        .command('init')
+        .description('create a .apisteadyrc.yml config in the current directory')
+        .option('-i, --input <spec>', 'path or URL of the OpenAPI document (detected when omitted)')
+        .option('-o, --output <dir>', 'output directory for the SDK', './sdk')
+        .option('-f, --force', 'overwrite an existing config')
+        .action(action(initCommand));
+    program
+        .command('generate')
+        .alias('gen')
+        .description('generate the SDK, keeping your own files and existing names intact')
+        .option('-c, --config <file>', 'config file (default: nearest .apisteadyrc.yml)')
+        .option('-i, --input <spec>', 'OpenAPI document, overriding the config')
+        .option('-o, --output <dir>', 'output directory, overriding the config')
+        .option('--no-validate', 'skip OpenAPI validation')
+        .option('--dry-run', 'show what would change without writing')
+        .option('--check', 'exit 1 if the SDK on disk is out of date (for CI)')
+        .option('--relock', 'ignore the name lock and re-derive names from the rules')
+        .option('-f, --force', 'overwrite generated files even if they were edited by hand')
+        .option('--verbose', 'show notes and unchanged files')
+        .action(action(generateCommand));
+    program
+        .command('watch')
+        .description('generate, then regenerate whenever the spec, a file it references or the config changes')
+        .option('-c, --config <file>', 'config file (default: nearest .apisteadyrc.yml)')
+        .option('-i, --input <spec>', 'OpenAPI document, overriding the config')
+        .option('-o, --output <dir>', 'output directory, overriding the config')
+        .option('--no-validate', 'skip OpenAPI validation')
+        .option('--verbose', 'show notes and unchanged files')
+        .action(action(watchCommand));
+    const specArguments = (command) => command
+        .argument('[old]', 'spec to compare from (default: the spec the SDK was last generated from); <git-rev>:<path> reads it from git')
+        .argument('[new]', 'spec to compare to (default: the configured input)')
+        .option('-c, --config <file>', 'config file (default: nearest .apisteadyrc.yml)')
+        .option('-i, --input <spec>', 'use this spec instead of the configured input as [new]')
+        .option('-b, --base <git-rev>', 'compare against the configured spec as it is at this git revision, e.g. origin/main')
+        .option('--no-validate', 'skip OpenAPI validation')
+        .option('--json', 'print the changes as JSON');
+    specArguments(program.command('diff'))
+        .description('list API changes, marking breaking ones (default: since the last generation)')
+        .option('--fail-on-breaking', 'exit 1 if any change is breaking (for CI)')
+        .option('--require-bump', 'exit 1 if there are breaking changes but info.version is not a new major version (for CI)')
+        .action(action(diffCommand));
+    specArguments(program.command('changelog'))
+        .description('write the API changes as a Markdown changelog entry')
+        .option('--out <file>', 'write to a file instead of stdout')
+        .action(action(changelogCommand));
+    program
+        .command('eject')
+        .description('copy a built-in template into your project to customize it')
+        .addArgument(new Argument('<template>', 'template to copy').choices(TEMPLATE_NAMES))
+        .option('-c, --config <file>', 'config file (default: nearest .apisteadyrc.yml)')
+        .option('--out <file>', 'where to write it (default: templates.<template> from the config, or ./apisteady/<template>.ts)')
+        .option('--stdout', 'print it instead, e.g. to compare with your copy')
+        .option('-f, --force', 'replace an existing file')
+        .action(action(ejectCommand));
+    try {
+        await program.parseAsync([...argv], { from: 'user' });
+    }
+    catch (error) {
+        if (error instanceof CommanderError) {
+            // --help and --version also arrive here, with exit code 0.
+            return error.exitCode;
+        }
+        throw error;
+    }
+    return exitCode;
+}
+//# sourceMappingURL=cli.js.map

package/dist/commands/changelog.d.ts

@@ -0,0 +1,8 @@
+import type { Ui } from '../ui.js';
+import { type DiffCommandOptions } from './diff.js';
+export interface ChangelogCommandOptions extends Pick<DiffCommandOptions, 'config' | 'input' | 'base' | 'validate' | 'json'> {
+    out?: string;
+}
+/** Markdown (or JSON) release notes for the API changes, on stdout or into a file. */
+export declare function changelogCommand(ui: Ui, options: ChangelogCommandOptions, args: ReadonlyArray<string | undefined>): Promise<number>;
+//# sourceMappingURL=changelog.d.ts.map

package/dist/commands/changelog.js

@@ -0,0 +1,20 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { renderChangelog, serializeDiff } from '@apisteady/core';
+import { compareSpecs } from './diff.js';
+/** Markdown (or JSON) release notes for the API changes, on stdout or into a file. */
+export async function changelogCommand(ui, options, args) {
+    const { diff } = await compareSpecs(ui, args, options);
+    const content = options.json ? serializeDiff(diff) : renderChangelog(diff);
+    if (options.out === undefined) {
+        ui.io.stdout(content);
+        return 0;
+    }
+    const target = path.resolve(ui.io.cwd, options.out);
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, content, 'utf8');
+    const { breaking, nonBreaking } = diff.summary;
+    ui.success(`Wrote ${ui.c.bold(ui.rel(target))} (${breaking} breaking, ${nonBreaking} non-breaking)`);
+    return 0;
+}
+//# sourceMappingURL=changelog.js.map

package/dist/commands/diff.d.ts

@@ -0,0 +1,24 @@
+import { type ApiDiff } from '@apisteady/core';
+import type { Ui } from '../ui.js';
+export interface DiffCommandOptions {
+    config?: string;
+    input?: string;
+    base?: string;
+    validate?: boolean;
+    json?: boolean;
+    failOnBreaking?: boolean;
+    requireBump?: boolean;
+}
+export interface ComparedSpecs {
+    diff: ApiDiff;
+    /** Where each side came from (file path or URL). */
+    from: string;
+    to: string;
+}
+/**
+ * Resolves the two sides of a comparison. `old` defaults to the spec the SDK was last generated from
+ * (`<output>/.apisteady/spec.json`), `new` to the configured input; a config is only needed for those defaults.
+ */
+export declare function compareSpecs(ui: Ui, [oldSpec, newSpec]: ReadonlyArray<string | undefined>, options: Pick<DiffCommandOptions, 'config' | 'input' | 'base' | 'validate'>): Promise<ComparedSpecs>;
+export declare function diffCommand(ui: Ui, options: DiffCommandOptions, args: ReadonlyArray<string | undefined>): Promise<number>;
+//# sourceMappingURL=diff.d.ts.map

package/dist/commands/diff.js

@@ -0,0 +1,98 @@
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+import { applyIgnore, buildModel, checkVersionBump, isApiSteadyError, diffModels, diffTitle, loadConfig, loadSpec, loadSpecSnapshot, parseRevisionArgument, ApiSteadyError, serializeDiff, } from '@apisteady/core';
+import { printChanges } from '../changes.js';
+/**
+ * Resolves the two sides of a comparison. `old` defaults to the spec the SDK was last generated from
+ * (`<output>/.apisteady/spec.json`), `new` to the configured input; a config is only needed for those defaults.
+ */
+export async function compareSpecs(ui, [oldSpec, newSpec], options) {
+    if (oldSpec !== undefined && options.base !== undefined) {
+        throw new ApiSteadyError('ARGUMENTS_INVALID', 'Pass either an [old] spec or --base, not both', {
+            hint: '`--base main` compares the configured spec as it is on main; `main:openapi.yaml` names a file at a revision.',
+        });
+    }
+    const validate = options.validate !== false;
+    let pending;
+    const config = () => (pending ??= loadConfig({
+        cwd: ui.io.cwd,
+        configPath: options.config,
+        overrides: {
+            ...(options.input !== undefined && { input: options.input }),
+            ...(!validate && { validate: false }),
+        },
+    }));
+    const from = oldSpec !== undefined
+        ? await loadArgument(ui, oldSpec, validate)
+        : options.base !== undefined
+            ? await atBase(ui, await config(), options.base)
+            : await lastGenerated(ui, await config());
+    const to = newSpec !== undefined
+        ? await loadArgument(ui, newSpec, validate)
+        : await config().then((resolved) => loadSpec(resolved.inputPath, { validate: resolved.validate }));
+    // When the comparison involves the SDK's config, compare what the SDK covers: apply its ignore list.
+    const ignore = pending && (await pending).ignore;
+    const model = (spec) => (ignore ? applyIgnore(buildModel(spec.document), ignore) : buildModel(spec.document));
+    const head = model(to);
+    const base = from === 'missing' ? { ...head, version: 'none', operations: [], webhooks: [], schemas: [], securitySchemes: [], servers: [] } : model(from);
+    return { diff: diffModels(base, head), from: from === 'missing' ? `${options.base} (no spec yet)` : from.source, to: to.source };
+}
+/** A spec argument: a file, a URL, or `<revision>:<path>` to read it from git (`main:openapi.yaml`). */
+async function loadArgument(ui, argument, validate) {
+    const onDisk = await stat(path.resolve(ui.io.cwd, argument)).catch(() => undefined);
+    const atRevision = onDisk ? undefined : parseRevisionArgument(argument);
+    return atRevision
+        ? loadSpec(atRevision.file, { cwd: ui.io.cwd, validate, revision: atRevision.revision })
+        : loadSpec(argument, { cwd: ui.io.cwd, validate });
+}
+/** The configured spec at a git revision; 'missing' when it did not exist yet, so everything in it is new. */
+async function atBase(ui, config, revision) {
+    try {
+        return await loadSpec(config.inputPath, { validate: config.validate, revision });
+    }
+    catch (error) {
+        if (!isApiSteadyError(error) || error.code !== 'SPEC_NOT_FOUND')
+            throw error;
+        ui.io.stderr(`${ui.c.dim(`${ui.rel(config.inputPath)} does not exist at ${revision}; every endpoint counts as new.`)}\n`);
+        return 'missing';
+    }
+}
+async function lastGenerated(ui, config) {
+    const snapshot = await loadSpecSnapshot(config.outputDir);
+    if (snapshot)
+        return snapshot;
+    throw new ApiSteadyError('BASELINE_NOT_FOUND', `No generated SDK found in ${ui.rel(config.outputDir)} to compare against`, {
+        hint: 'Run `apisteady generate` first, or compare two files: `apisteady diff old.yaml new.yaml`.',
+    });
+}
+export async function diffCommand(ui, options, args) {
+    const { diff, from, to } = await compareSpecs(ui, args, options);
+    if (options.json) {
+        ui.io.stdout(serializeDiff(diff));
+    }
+    else {
+        ui.line(ui.c.dim(`Comparing ${ui.rel(from)} → ${ui.rel(to)}`));
+        if (diff.changes.length === 0)
+            ui.success(`No API changes (${diffTitle(diff)})`);
+        else
+            printChanges(ui, diff, { heading: `API changes in ${diffTitle(diff)}` });
+    }
+    let exitCode = 0;
+    if (options.requireBump) {
+        const check = checkVersionBump(diff);
+        if (!check.ok) {
+            ui.fail(`${check.message} (--require-bump)`);
+            exitCode = 1;
+        }
+        else if (diff.summary.breaking > 0 && !options.json) {
+            ui.success(check.message);
+        }
+    }
+    if (options.failOnBreaking && diff.summary.breaking > 0) {
+        const { breaking } = diff.summary;
+        ui.fail(`${breaking} breaking change${breaking === 1 ? '' : 's'} (--fail-on-breaking)`);
+        exitCode = 1;
+    }
+    return exitCode;
+}
+//# sourceMappingURL=diff.js.map

package/dist/commands/eject.d.ts

@@ -0,0 +1,10 @@
+import type { Ui } from '../ui.js';
+export interface EjectCommandOptions {
+    config?: string;
+    out?: string;
+    stdout?: boolean;
+    force?: boolean;
+}
+/** Copies a built-in template into the project so it can be customized (`templates.<name>` in the config). */
+export declare function ejectCommand(ui: Ui, options: EjectCommandOptions, [name]: ReadonlyArray<string | undefined>): Promise<number>;
+//# sourceMappingURL=eject.d.ts.map

package/dist/commands/eject.js

@@ -0,0 +1,43 @@
+import { mkdir, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { ejectTemplate, isApiSteadyError, loadConfig, ApiSteadyError } from '@apisteady/core';
+/** Copies a built-in template into the project so it can be customized (`templates.<name>` in the config). */
+export async function ejectCommand(ui, options, [name]) {
+    const template = name;
+    const content = await ejectTemplate(template);
+    if (options.stdout) {
+        ui.io.stdout(content);
+        return 0;
+    }
+    const config = await findConfig(ui, options.config);
+    const base = config?.rootDir ?? ui.io.cwd;
+    const target = options.out !== undefined ? path.resolve(ui.io.cwd, options.out) : (config?.runtimeTemplatePath ?? path.join(base, 'apisteady', `${template}.ts`));
+    if (!options.force && (await stat(target).catch(() => undefined))) {
+        throw new ApiSteadyError('FILE_EXISTS', `${ui.rel(target)} already exists`, {
+            hint: 'Pass --force to replace it (your changes to it are lost), or --stdout to compare it with the built-in version.',
+        });
+    }
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, content, 'utf8');
+    ui.success(`Copied the built-in ${template} template to ${ui.c.bold(ui.rel(target))}`);
+    if (config?.runtimeTemplatePath === target) {
+        ui.line(`apisteady uses it for generated/${template}.ts from the next run on.`);
+    }
+    else {
+        const relative = path.relative(base, target).split(path.sep).join('/');
+        ui.line(`To use it, add this to ${config?.configPath ? ui.rel(config.configPath) : 'your apisteady config'}:`);
+        ui.line(ui.c.cyan(`  templates:\n    ${template}: ${relative.startsWith('.') ? relative : `./${relative}`}`));
+    }
+    return 0;
+}
+async function findConfig(ui, configPath) {
+    try {
+        return await loadConfig({ cwd: ui.io.cwd, configPath });
+    }
+    catch (error) {
+        if (isApiSteadyError(error) && error.code === 'CONFIG_NOT_FOUND' && configPath === undefined)
+            return undefined;
+        throw error;
+    }
+}
+//# sourceMappingURL=eject.js.map

package/dist/commands/generate.d.ts

@@ -0,0 +1,23 @@
+import { type GenerateResult, type ResolvedConfig } from '@apisteady/core';
+import type { Ui } from '../ui.js';
+export interface GenerateCommandOptions {
+    config?: string;
+    input?: string;
+    output?: string;
+    validate?: boolean;
+    dryRun?: boolean;
+    check?: boolean;
+    relock?: boolean;
+    force?: boolean;
+    verbose?: boolean;
+}
+export declare function generateCommand(ui: Ui, options: GenerateCommandOptions): Promise<number>;
+/** The config with `--config`, `--input`, `--output` and `--no-validate` applied. */
+export declare function loadGenerateConfig(ui: Ui, options: Pick<GenerateCommandOptions, 'config' | 'input' | 'output' | 'validate'>): Promise<ResolvedConfig>;
+/** What was loaded, diagnostics, API changes, the files touched, and the outcome. */
+export declare function printGeneration(ui: Ui, result: GenerateResult, options: {
+    dryRun: boolean;
+    force?: boolean | undefined;
+    verbose?: boolean | undefined;
+}, started: number): void;
+//# sourceMappingURL=generate.d.ts.map

package/dist/commands/generate.js

@@ -0,0 +1,104 @@
+import { describeConflict, generate, hasChanges, loadConfig, MANIFEST_FILE, } from '@apisteady/core';
+import { printChanges } from '../changes.js';
+const SYMBOLS = { create: '+', update: '~', delete: '-', unchanged: ' ', keep: '=' };
+export async function generateCommand(ui, options) {
+    const started = performance.now();
+    const config = await loadGenerateConfig(ui, options);
+    if (config.configPath)
+        ui.line(ui.c.dim(`Using ${ui.rel(config.configPath)}`));
+    const dryRun = options.dryRun === true || options.check === true;
+    const result = await generate({ config, dryRun, relock: options.relock === true, force: options.force === true });
+    if (options.check) {
+        printSummary(ui, result, options.verbose === true);
+        return reportCheck(ui, result.plan);
+    }
+    printGeneration(ui, result, { ...options, dryRun }, started);
+    return 0;
+}
+/** The config with `--config`, `--input`, `--output` and `--no-validate` applied. */
+export function loadGenerateConfig(ui, options) {
+    return loadConfig({
+        cwd: ui.io.cwd,
+        configPath: options.config,
+        overrides: {
+            ...(options.input !== undefined && { input: options.input }),
+            ...(options.output !== undefined && { output: options.output }),
+            ...(options.validate === false && { validate: false }),
+        },
+    });
+}
+/** What was loaded, diagnostics, API changes, the files touched, and the outcome. */
+export function printGeneration(ui, result, options, started) {
+    const { plan } = result;
+    printSummary(ui, result, options.verbose === true);
+    printPlan(ui, plan, options.verbose === true);
+    const elapsed = Math.round(performance.now() - started);
+    if (options.dryRun) {
+        ui.info(`Dry run: nothing was written ${ui.c.dim(`(${elapsed} ms)`)}`);
+        if (plan.conflicts.length > 0 && !options.force) {
+            ui.warn('A real run would stop here: these files were changed outside apisteady (use --force to overwrite):');
+            for (const conflict of plan.conflicts)
+                ui.line(`    ${describeConflict(conflict)}`);
+        }
+    }
+    else {
+        ui.success(`SDK written to ${ui.c.bold(ui.rel(plan.outputDir))} ${ui.c.dim(`(${elapsed} ms)`)}`);
+    }
+}
+function printSummary(ui, result, verbose) {
+    const { model, spec } = result;
+    ui.success(`Loaded ${ui.c.bold(`${model.title} ${model.version}`)} (${spec.convertedFrom ? `Swagger ${spec.convertedFrom}, read as OpenAPI 3.0` : `OpenAPI ${spec.openapiVersion}`}): ` +
+        `${count(model.operations.length, 'operation')}, ${count(model.schemas.length, 'schema')}`);
+    ui.diagnostics(result.diagnostics, verbose);
+    if (result.changes && result.changes.changes.length > 0) {
+        const { from, to } = result.changes;
+        printChanges(ui, result.changes, {
+            heading: `API changes since the last generation${from.version === to.version ? '' : ` (${from.version} → ${to.version})`}`,
+            limit: verbose ? undefined : 10,
+            moreHint: 'run with --verbose to list them all',
+        });
+    }
+}
+function printPlan(ui, plan, verbose) {
+    const tally = { create: 0, update: 0, delete: 0, unchanged: 0, keep: 0 };
+    for (const change of plan.changes) {
+        if (change.ownership === 'meta')
+            continue;
+        tally[change.action]++;
+        const quiet = change.action === 'unchanged' || (change.action === 'keep' && change.ownership === 'scaffold');
+        if (quiet && !verbose)
+            continue;
+        const color = { create: ui.c.green, update: ui.c.yellow, delete: ui.c.red, unchanged: ui.c.dim, keep: ui.c.dim }[change.action];
+        const note = change.action === 'keep' ? ui.c.dim(change.ownership === 'scaffold' ? '  (yours, left as is)' : '  (edited, left in place)') : '';
+        ui.line(`  ${color(`${SYMBOLS[change.action]} ${change.path}`)}${note}`);
+    }
+    const parts = [
+        tally.create && `${tally.create} created`,
+        tally.update && `${tally.update} updated`,
+        tally.delete && `${tally.delete} deleted`,
+        tally.unchanged && `${tally.unchanged} unchanged`,
+    ].filter(Boolean);
+    ui.line(ui.c.dim(`  ${parts.join(', ') || 'no files'}`));
+}
+/** `--check`: exit 1 when the SDK on disk is not what the current spec and config would produce. */
+function reportCheck(ui, plan) {
+    // The manifest also records the apisteady version; upgrading apisteady alone should not fail CI.
+    const outdated = { ...plan, changes: plan.changes.filter((change) => change.path !== MANIFEST_FILE) };
+    if (!hasChanges(outdated) && plan.conflicts.length === 0) {
+        ui.success('SDK is up to date');
+        return 0;
+    }
+    ui.fail('SDK is out of date with the spec or config. Run `apisteady generate` and commit the result.');
+    for (const change of outdated.changes) {
+        if (change.action === 'create' || change.action === 'update' || change.action === 'delete') {
+            ui.io.stderr(`  ${SYMBOLS[change.action]} ${change.path}\n`);
+        }
+    }
+    for (const conflict of plan.conflicts)
+        ui.io.stderr(`  ! ${describeConflict(conflict)}\n`);
+    return 1;
+}
+function count(n, noun) {
+    return `${n} ${noun}${n === 1 ? '' : 's'}`;
+}
+//# sourceMappingURL=generate.js.map

package/dist/commands/init.d.ts

@@ -0,0 +1,9 @@
+import type { Ui } from '../ui.js';
+export interface InitCommandOptions {
+    input?: string;
+    output?: string;
+    force?: boolean;
+}
+export declare const CONFIG_FILE = ".apisteadyrc.yml";
+export declare function initCommand(ui: Ui, options: InitCommandOptions): Promise<number>;
+//# sourceMappingURL=init.d.ts.map

package/dist/commands/init.js

@@ -0,0 +1,111 @@
+import { readdir, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { buildModel, loadSpec, parseConfig, ApiSteadyError } from '@apisteady/core';
+import { parse as parseYaml } from 'yaml';
+export const CONFIG_FILE = '.apisteadyrc.yml';
+const SPEC_CANDIDATES = /^(openapi|swagger|api|spec)([.-][\w.-]+)?\.(ya?ml|json)$/i;
+/** Where specs usually live, besides the project root. */
+const SPEC_DIRECTORIES = ['api', 'apis', 'spec', 'specs', 'openapi', 'docs', 'schema'];
+const EXAMPLE_CONFIG = 'https://github.com/euruuuuu/steadysdk/blob/main/.apisteadyrc.example.yml';
+export async function initCommand(ui, options) {
+    const target = path.join(ui.io.cwd, CONFIG_FILE);
+    if (!options.force && (await stat(target).catch(() => undefined))) {
+        throw new ApiSteadyError('CONFIG_EXISTS', `${CONFIG_FILE} already exists`, { hint: 'Pass --force to overwrite it.' });
+    }
+    const candidates = options.input === undefined ? await detectSpecs(ui.io.cwd) : [];
+    const input = options.input ?? candidates[0];
+    const output = options.output ?? './sdk';
+    const content = configTemplate(input ?? './openapi.yaml', output);
+    parseConfig(parseYaml(content), 'init template'); // never write a config apisteady itself would reject
+    await writeFile(target, content, 'utf8');
+    ui.success(`Created ${ui.c.bold(CONFIG_FILE)}`);
+    if (input === undefined) {
+        ui.warn('No OpenAPI file found here; set `input` in the config to your spec.');
+    }
+    else {
+        const what = await describeSpec(ui, input);
+        if (options.input === undefined)
+            ui.info(`Detected spec ${ui.c.bold(input)}${what ? ` ${ui.c.dim(`(${what})`)}` : ''}`);
+        else if (what)
+            ui.info(`Spec ${ui.c.bold(input)} ${ui.c.dim(`(${what})`)}`);
+        if (candidates.length > 1)
+            ui.line(ui.c.dim(`  Also found: ${candidates.slice(1).join(', ')}. Change \`input\` to use one of those.`));
+    }
+    // When run through npx, suggest commands that work the same way.
+    const cli = process.env['npm_command'] === 'exec' ? 'npx apisteady' : 'apisteady';
+    ui.line();
+    ui.line('Next steps:');
+    ui.line(`  1. Review ${CONFIG_FILE}: naming rules, grouping, parts of the API to leave out`);
+    ui.line(`     ${ui.c.dim(`Every option: ${EXAMPLE_CONFIG}`)}`);
+    ui.line(`  2. Generate the SDK:         ${ui.c.cyan(`${cli} generate`)}`);
+    ui.line(`  3. Commit ${output.replace(/^\.\//, '')}/, including its .apisteady/ folder (it keeps names stable)`);
+    ui.line(`  4. Keep it in sync in CI:    ${ui.c.cyan(`${cli} generate --check`)}`);
+    ui.line();
+    ui.line(ui.c.dim(`While you edit the spec, ${cli} watch regenerates on every save.`));
+    return 0;
+}
+/** Spec files in the project root, then in the usual spec directories; `openapi.*` first. */
+async function detectSpecs(cwd) {
+    const found = [];
+    for (const directory of ['', ...SPEC_DIRECTORIES]) {
+        const entries = await readdir(path.join(cwd, directory)).catch(() => []);
+        const matches = entries.filter((entry) => SPEC_CANDIDATES.test(entry)).sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
+        found.push(...matches.map((entry) => `./${directory === '' ? entry : `${directory}/${entry}`}`));
+    }
+    return found;
+}
+function rank(file) {
+    return file.toLowerCase().startsWith('openapi') ? 0 : 1;
+}
+/** `Petstore 1.0.0, OpenAPI 3.0.3, 11 operations`, or a warning when the file cannot be read. */
+async function describeSpec(ui, input) {
+    try {
+        const spec = await loadSpec(input, { cwd: ui.io.cwd, validate: false });
+        const model = buildModel(spec.document);
+        const format = spec.convertedFrom ? `Swagger ${spec.convertedFrom}` : `OpenAPI ${spec.openapiVersion}`;
+        const count = model.operations.length;
+        return `${model.title} ${model.version}, ${format}, ${count} operation${count === 1 ? '' : 's'}`;
+    }
+    catch (error) {
+        ui.warn(`Could not read ${input} as an OpenAPI spec yet: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+}
+function configTemplate(input, output) {
+    return `# apisteady configuration. Paths are relative to this file.
+# Every option is documented in .apisteadyrc.example.yml in the apisteady repository.
+
+# OpenAPI 3.0 / 3.1 document: YAML or JSON, file path or URL.
+input: ${yamlString(input)}
+
+# Where the SDK goes. apisteady owns <output>/generated/ and .apisteady/; everything else there is yours.
+output: ${yamlString(output)}
+
+client:
+  # name: MyApiClient     # root client class; defaults to the spec title + "Client"
+  groupBy: auto           # auto | tag | path | none  (auto: by tag if the spec uses tags, else by path)
+  # baseUrl: https://api.example.com
+
+naming:
+  # Words kept in a fixed form, e.g. [ID, API, URL] turns userId into userID.
+  acronyms: []
+  operations:
+    case: camel           # camel | pascal | snake | constant | preserve
+    source: operationId   # operationId (fall back to path) | path
+    # stripPrefixes: ['^\\w+Controller_']   # NestJS-style operationIds
+  types:
+    case: pascal
+    # suffix: Dto
+  parameters:
+    case: camel
+  # Keep names stable across regenerations (.apisteady/names.lock.json).
+  lock: true
+  overrides:
+    operations: {}        # "GET /users/{id}": fetchUser   or   listPets: getAllPets
+    schemas: {}           # UserDTO: User
+`;
+}
+function yamlString(value) {
+    return /^[\w./-]+$/.test(value) ? value : JSON.stringify(value);
+}
+//# sourceMappingURL=init.js.map

package/dist/commands/watch.d.ts

@@ -0,0 +1,9 @@
+import type { Ui } from '../ui.js';
+import { type GenerateCommandOptions } from './generate.js';
+export type WatchCommandOptions = Pick<GenerateCommandOptions, 'config' | 'input' | 'output' | 'validate' | 'verbose'>;
+/**
+ * Generates, then regenerates whenever the spec (including files it `$ref`s), the config or the runtime
+ * template changes. Errors (an invalid spec mid-edit, a conflict) are reported and watching continues.
+ */
+export declare function watchCommand(ui: Ui, options: WatchCommandOptions): Promise<number>;
+//# sourceMappingURL=watch.d.ts.map

package/dist/commands/watch.js

@@ -0,0 +1,98 @@
+import { generate, ApiSteadyError } from '@apisteady/core';
+import { FileWatcher } from '../watcher.js';
+import { loadGenerateConfig, printGeneration } from './generate.js';
+/** Saves arrive as bursts of file events; wait for the burst to end before regenerating. */
+const SETTLE_MS = 100;
+/**
+ * Generates, then regenerates whenever the spec (including files it `$ref`s), the config or the runtime
+ * template changes. Errors (an invalid spec mid-edit, a conflict) are reported and watching continues.
+ */
+export async function watchCommand(ui, options) {
+    // Without a usable config there is nothing to watch, so that one is fatal.
+    let config = await loadGenerateConfig(ui, options);
+    assertWatchable(config);
+    if (config.configPath)
+        ui.line(ui.c.dim(`Using ${ui.rel(config.configPath)}`));
+    const interrupt = ui.io.signal ? { signal: ui.io.signal, dispose: () => { } } : onInterrupt();
+    let timer;
+    let running;
+    let queued;
+    const watcher = new FileWatcher((file) => {
+        queued ??= file;
+        clearTimeout(timer);
+        timer = setTimeout(() => void cycle(), SETTLE_MS);
+    });
+    const regenerate = async () => {
+        const started = performance.now();
+        const files = new Set([config.inputPath, config.configPath, config.runtimeTemplatePath].filter((file) => file !== undefined));
+        try {
+            const result = await generate({ config });
+            for (const file of result.spec.files)
+                files.add(file);
+            printGeneration(ui, result, { dryRun: false, verbose: options.verbose }, started);
+        }
+        catch (error) {
+            ui.error(error);
+        }
+        watcher.set(files);
+    };
+    const cycle = async () => {
+        if (running)
+            return; // the running cycle picks up `queued` when it finishes
+        const file = queued;
+        queued = undefined;
+        if (file === undefined || interrupt.signal.aborted)
+            return;
+        running = (async () => {
+            ui.line();
+            ui.line(ui.c.dim(`[${new Date().toTimeString().slice(0, 8)}] ${ui.rel(file)} changed`));
+            try {
+                config = await loadGenerateConfig(ui, options);
+                assertWatchable(config);
+                await regenerate();
+            }
+            catch (error) {
+                ui.error(error); // e.g. the config is mid-edit: keep watching what we had
+            }
+        })();
+        await running;
+        running = undefined;
+        if (queued !== undefined)
+            await cycle();
+    };
+    await regenerate();
+    ui.info(`Watching ${watcher.size} file${watcher.size === 1 ? '' : 's'} for changes. Press Ctrl+C to stop.`);
+    await new Promise((resolve) => {
+        if (interrupt.signal.aborted)
+            resolve();
+        else
+            interrupt.signal.addEventListener('abort', () => resolve(), { once: true });
+    });
+    clearTimeout(timer);
+    watcher.close();
+    interrupt.dispose();
+    await running;
+    ui.line(ui.c.dim('Stopped watching.'));
+    return 0;
+}
+function assertWatchable(config) {
+    if (/^https?:\/\//i.test(config.inputPath)) {
+        throw new ApiSteadyError('WATCH_UNSUPPORTED', `Cannot watch ${config.inputPath}: it is a URL`, {
+            hint: 'Watch mode needs the spec on disk. Download it, or run `apisteady generate` when it changes.',
+        });
+    }
+}
+function onInterrupt() {
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    return {
+        signal: controller.signal,
+        dispose: () => {
+            process.off('SIGINT', stop);
+            process.off('SIGTERM', stop);
+        },
+    };
+}
+//# sourceMappingURL=watch.js.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from './cli.js';
+process.exitCode = await run(process.argv.slice(2));
+//# sourceMappingURL=index.js.map

package/dist/ui.d.ts

@@ -0,0 +1,30 @@
+import pc from 'picocolors';
+import { type Diagnostic } from '@apisteady/core';
+export interface Io {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    cwd: string;
+    /** Colors are on for TTYs unless NO_COLOR is set; tests pass false. */
+    color: boolean;
+    /** Stops long-running commands (`watch`). Without it they stop on Ctrl+C. */
+    signal?: AbortSignal | undefined;
+}
+export declare function defaultIo(): Io;
+/** Small presentation layer so commands read as a sequence of steps. */
+export declare class Ui {
+    readonly io: Io;
+    private readonly colors;
+    constructor(io: Io);
+    get c(): ReturnType<typeof pc.createColors>;
+    line(text?: string): void;
+    success(text: string): void;
+    warn(text: string): void;
+    info(text: string): void;
+    fail(text: string): void;
+    /** A path relative to the working directory, for display. */
+    rel(target: string): string;
+    diagnostics(items: readonly Diagnostic[], verbose: boolean): void;
+    error(error: unknown): void;
+    private formatDiagnostic;
+}
+//# sourceMappingURL=ui.d.ts.map

package/dist/ui.js

@@ -0,0 +1,75 @@
+import path from 'node:path';
+import pc from 'picocolors';
+import { isApiSteadyError } from '@apisteady/core';
+export function defaultIo() {
+    return {
+        stdout: (text) => process.stdout.write(text),
+        stderr: (text) => process.stderr.write(text),
+        cwd: process.cwd(),
+        color: pc.isColorSupported,
+    };
+}
+/** Small presentation layer so commands read as a sequence of steps. */
+export class Ui {
+    io;
+    colors;
+    constructor(io) {
+        this.io = io;
+        this.colors = pc.createColors(io.color);
+    }
+    get c() {
+        return this.colors;
+    }
+    line(text = '') {
+        this.io.stdout(`${text}\n`);
+    }
+    success(text) {
+        this.line(`${this.colors.green('✔')} ${text}`);
+    }
+    warn(text) {
+        this.line(`${this.colors.yellow('⚠')} ${text}`);
+    }
+    info(text) {
+        this.line(`${this.colors.cyan('ℹ')} ${text}`);
+    }
+    fail(text) {
+        this.io.stderr(`${this.colors.red('✖')} ${text}\n`);
+    }
+    /** A path relative to the working directory, for display. */
+    rel(target) {
+        if (/^https?:\/\//i.test(target))
+            return target;
+        const relative = path.relative(this.io.cwd, target);
+        return relative === '' ? '.' : relative.startsWith('..') ? target : relative;
+    }
+    diagnostics(items, verbose) {
+        const warnings = items.filter((item) => item.level === 'warning');
+        const notes = items.filter((item) => item.level === 'info');
+        for (const item of warnings)
+            this.warn(this.formatDiagnostic(item));
+        if (verbose) {
+            for (const item of notes)
+                this.info(this.formatDiagnostic(item));
+        }
+        else if (notes.length > 0) {
+            this.line(this.colors.dim(`  ${notes.length} note${notes.length === 1 ? '' : 's'} hidden (run with --verbose to see them)`));
+        }
+    }
+    error(error) {
+        if (isApiSteadyError(error)) {
+            this.fail(error.message);
+            for (const detail of error.details)
+                this.io.stderr(`  ${this.colors.dim('•')} ${detail}\n`);
+            if (error.hint)
+                this.io.stderr(`  ${this.colors.cyan('Hint:')} ${error.hint}\n`);
+            return;
+        }
+        this.fail('Unexpected error — this is a bug in apisteady, please report it.');
+        this.io.stderr(`${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+    }
+    formatDiagnostic(item) {
+        const where = item.location ? this.colors.dim(` (${item.location})`) : '';
+        return `${item.message}${where}`;
+    }
+}
+//# sourceMappingURL=ui.js.map

package/dist/watcher.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Watches a changing set of files. It watches their directories rather than the files themselves:
+ * many editors save by writing a new file and renaming it over the old one, which a file watch misses.
+ */
+export declare class FileWatcher {
+    private readonly onChange;
+    private readonly watchers;
+    private files;
+    constructor(onChange: (file: string) => void);
+    get size(): number;
+    /** Replaces the watched files. Directories that cannot be watched (yet) are retried on the next call. */
+    set(files: Iterable<string>): void;
+    close(): void;
+}
+//# sourceMappingURL=watcher.d.ts.map

package/dist/watcher.js

@@ -0,0 +1,51 @@
+import { watch } from 'node:fs';
+import path from 'node:path';
+/**
+ * Watches a changing set of files. It watches their directories rather than the files themselves:
+ * many editors save by writing a new file and renaming it over the old one, which a file watch misses.
+ */
+export class FileWatcher {
+    onChange;
+    watchers = new Map();
+    files = new Set();
+    constructor(onChange) {
+        this.onChange = onChange;
+    }
+    get size() {
+        return this.files.size;
+    }
+    /** Replaces the watched files. Directories that cannot be watched (yet) are retried on the next call. */
+    set(files) {
+        this.files = new Set([...files].map((file) => path.resolve(file)));
+        const directories = new Set([...this.files].map((file) => path.dirname(file)));
+        for (const [directory, watcher] of this.watchers) {
+            if (directories.has(directory))
+                continue;
+            watcher.close();
+            this.watchers.delete(directory);
+        }
+        for (const directory of directories) {
+            if (this.watchers.has(directory))
+                continue;
+            try {
+                const watcher = watch(directory, (_event, name) => {
+                    // Some platforms omit the name; then any change in the directory counts.
+                    const file = name === null ? undefined : path.join(directory, name.toString());
+                    if (file === undefined || this.files.has(file))
+                        this.onChange(file ?? directory);
+                });
+                watcher.on('error', () => this.watchers.delete(directory));
+                this.watchers.set(directory, watcher);
+            }
+            catch {
+                // The directory does not exist right now.
+            }
+        }
+    }
+    close() {
+        for (const watcher of this.watchers.values())
+            watcher.close();
+        this.watchers.clear();
+    }
+}
+//# sourceMappingURL=watcher.js.map

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "apisteady",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Generate and maintain typed API client SDKs from OpenAPI specs",
+  "keywords": [
+    "openapi",
+    "swagger",
+    "sdk",
+    "sdk-generator",
+    "codegen",
+    "typescript",
+    "api-client",
+    "cli",
+    "changelog",
+    "breaking-changes"
+  ],
+  "homepage": "https://github.com/euruuuuu/steadysdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/euruuuuu/steadysdk.git",
+    "directory": "packages/cli"
+  },
+  "bugs": "https://github.com/euruuuuu/steadysdk/issues",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "apisteady": "dist/index.js"
+  },
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "prepack": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -b --force"
+  },
+  "dependencies": {
+    "@apisteady/core": "^0.1.0",
+    "commander": "^15.0.0",
+    "picocolors": "^1.1.1",
+    "yaml": "^2.9.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}