rpc-dart 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rpc-dart contributors
+
+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,17 @@
-# Temporary Holding Version
+# @rpc-dart/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.
+Zero-config CLI that generates typed Dart bindings from tRPC v11 routers.
+
+Part of the [rpc-dart](https://github.com/AdityaJandu/rpc-dart) monorepo — end-to-end type safety for tRPC v11 backends consumed from Dart and Flutter.
+
+## Install
+
+```bash
+npm install cli
+```
+
+See the [documentation](../../docs/README.md) for the full CLI reference, concepts, and guides.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/bin/rpc-dart.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import {
+  checkContract,
+  cleanGenerated,
+  ConfigNotFoundError,
+  diffContract,
+  doctorChecks,
+  generate,
+  initWorkspace,
+  resolveTargets,
+  WatchSession,
+} from '../dist/index.js';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function flag(name) {
+  const index = args.indexOf(`--${name}`);
+  if (index === -1) return undefined;
+  return args[index + 1];
+}
+
+function hasFlag(name) {
+  return args.includes(`--${name}`);
+}
+
+function flagsObject() {
+  return {
+    config: flag('config'),
+    tsconfig: flag('tsconfig'),
+    entry: flag('entry'),
+    exportName: flag('export'),
+    out: flag('out'),
+    transformer: flag('transformer'),
+  };
+}
+
+function policiesFrom(target) {
+  return target.policies ?? { unserializablePolicy: 'error' };
+}
+
+async function main() {
+  const cwd = process.cwd();
+  const configsDir = cwd;
+
+  switch (command) {
+    case 'generate': {
+      const targets = await resolveTargets(configsDir, flagsObject());
+      for (const target of targets) {
+        const result = await generate({
+          tsconfigPath: target.tsconfigPath,
+          entryFile: target.entry,
+          exportName: target.exportName,
+          outDir: path.resolve(cwd, target.dart?.outDir ?? 'lib/src/api'),
+          transformer: target.transformer,
+          policies: policiesFrom(target),
+          force: hasFlag('force'),
+        });
+        const label = target.name ? ` [${target.name}]` : '';
+        console.log(
+          result.wrote
+            ? `wrote${label} ${result.files.length} files (contract ${result.hash.slice(0, 15)})`
+            : `contract unchanged${label}, no writes (${result.hash.slice(0, 15)})`,
+        );
+      }
+      return;
+    }
+    case 'watch': {
+      const targets = await resolveTargets(configsDir, flagsObject());
+      for (const target of targets) {
+        const session = new WatchSession({
+          tsconfigPath: target.tsconfigPath,
+          entryFile: target.entry,
+          exportName: target.exportName,
+          outDir: path.resolve(cwd, target.dart?.outDir ?? 'lib/src/api'),
+          transformer: target.transformer,
+          policies: policiesFrom(target),
+          debounceMs: Number(flag('debounce-ms') ?? 300),
+          onCycle: (cycle) =>
+            console.log(
+              cycle.changed
+                ? `[watch] re-emitted ${cycle.written} files in ${cycle.durationMs}ms (${cycle.hash.slice(0, 15)})`
+                : `[watch] contract unchanged in ${cycle.durationMs}ms`,
+            ),
+          onError: (error) => console.error(`[watch] transient error: ${error.message}`),
+        });
+        session.start();
+      }
+      console.log('[watch] started - press Ctrl+C to stop');
+      return;
+    }
+    case 'check': {
+      const targets = await resolveTargets(configsDir, flagsObject());
+      let drift = false;
+      for (const target of targets) {
+        const result = await checkContract({
+          tsconfigPath: target.tsconfigPath,
+          entryFile: target.entry,
+          exportName: target.exportName,
+          outDir: path.resolve(cwd, target.dart?.outDir ?? 'lib/src/api'),
+          transformer: target.transformer,
+          policies: policiesFrom(target),
+        });
+        if (result.ok) {
+          console.log('check: generated bindings are up to date');
+        } else {
+          drift = true;
+          console.error('check: drift detected');
+          for (const problem of result.problems) {
+            console.error(`  - ${problem}`);
+          }
+        }
+      }
+      if (drift) process.exitCode = 3;
+      return;
+    }
+    case 'diff': {
+      const targets = await resolveTargets(configsDir, flagsObject());
+      for (const target of targets) {
+        const result = await diffContract({
+          tsconfigPath: target.tsconfigPath,
+          entryFile: target.entry,
+          exportName: target.exportName,
+          transformer: target.transformer,
+          baselinePath: path.resolve(cwd, flag('baseline') ?? 'ir.snapshot.json'),
+          updateBaseline: hasFlag('update-baseline'),
+        });
+        for (const entry of result.entries) {
+          console.log(`${entry.breaking ? 'BREAKING' : 'ok      '}  ${entry.kind}  ${entry.path}  ${entry.detail}`);
+        }
+        console.log(`diff: ${result.breakingCount} breaking, ${result.nonBreakingCount} non-breaking`);
+        if (result.hasBreaking && hasFlag('fail-on-breaking')) {
+          process.exitCode = 4;
+        }
+      }
+      return;
+    }
+    case 'clean': {
+      const targets = await resolveTargets(configsDir, flagsObject());
+      for (const target of targets) {
+        const result = cleanGenerated(path.resolve(cwd, target.dart?.outDir ?? 'lib/src/api'));
+        console.log(`clean: removed ${result.removed.length} owned files`);
+      }
+      return;
+    }
+    case 'doctor': {
+      const targets = await resolveTargets(configsDir, flagsObject());
+      for (const target of targets) {
+        const label = target.name ? `[${target.name}] ` : '';
+        const checks = await doctorChecks({
+          tsconfigPath: target.tsconfigPath,
+          entryFile: target.entry,
+          exportName: target.exportName,
+          dartPackagePath: flag('dart-package')
+            ? path.resolve(cwd, flag('dart-package'))
+            : target.dart?.packagePath
+              ? path.resolve(cwd, target.dart.packagePath)
+              : undefined,
+        });
+        let failing = false;
+        for (const check of checks) {
+          console.log(`${check.status.toUpperCase().padEnd(5)} ${label}${check.name}: ${check.detail}`);
+          if (check.status === 'fail') failing = true;
+        }
+        if (failing) process.exitCode = 5;
+      }
+      return;
+    }
+    case 'init': {
+      const result = await initWorkspace(cwd, { flutterDirs: [] });
+      console.log(`init: wrote ${result.configPath}`);
+      console.log(`  entry: ${result.config.entry}`);
+      console.log(`  exportName: ${result.config.exportName}`);
+      console.log(`  dart.outDir: ${result.config.dart.outDir}`);
+      return;
+    }
+    default:
+      console.error(`rpc-dart: unknown command "${command ?? ''}"`);
+      console.error('commands: generate | watch | check | diff | clean | doctor | init');
+      process.exitCode = 2;
+  }
+}
+
+main().catch((error) => {
+  if (error instanceof ConfigNotFoundError) {
+    console.error(`rpc-dart: ${error.message}`);
+    process.exitCode = 2;
+  } else {
+    console.error(`rpc-dart: ${error.message}`);
+    process.exitCode = 1;
+  }
+});

package/dist/commands/check.d.ts

@@ -0,0 +1,11 @@
+import { type ExtractPolicies } from '@rpc-dart/trpc-adapter';
+import type { GenerateOptions } from './generate.js';
+export interface CheckResult {
+    ok: boolean;
+    problems: string[];
+}
+/**
+ * CI gate: re-extracts the contract, verifies the committed manifest hash and
+ * every manifest file's content against disk. Non-destructive.
+ */
+export declare function checkContract(options: Omit<GenerateOptions, 'force'>, policies?: ExtractPolicies): Promise<CheckResult>;

package/dist/commands/check.js

@@ -0,0 +1,39 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { extractContract } from '@rpc-dart/trpc-adapter';
+const MANIFEST_NAME = 'generated.rpc-dart.json';
+/**
+ * CI gate: re-extracts the contract, verifies the committed manifest hash and
+ * every manifest file's content against disk. Non-destructive.
+ */
+export async function checkContract(options, policies) {
+    const problems = [];
+    const { ir } = await extractContract({
+        tsconfigPath: options.tsconfigPath,
+        entryFile: options.entryFile,
+        exportName: options.exportName,
+        protocol: { kind: 'trpc', version: '11', transformer: options.transformer ?? 'superjson' },
+        policies,
+    });
+    const manifestPath = path.join(options.outDir, MANIFEST_NAME);
+    if (!existsSync(manifestPath)) {
+        return { ok: false, problems: ['no generated manifest found - run `rpc-dart generate` first'] };
+    }
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    if (manifest.irHash !== ir.hash) {
+        problems.push(`contract hash mismatch: router changed since last generate (manifest ${manifest.irHash.slice(0, 15)}, current ${ir.hash.slice(0, 15)})`);
+    }
+    for (const file of manifest.files) {
+        const target = path.join(options.outDir, file.path);
+        if (!existsSync(target)) {
+            problems.push(`missing generated file: ${file.path}`);
+            continue;
+        }
+        const actual = createHash('sha256').update(readFileSync(target, 'utf-8')).digest('hex');
+        if (actual !== file.contentSha256) {
+            problems.push(`generated file modified on disk: ${file.path}`);
+        }
+    }
+    return { ok: problems.length === 0, problems };
+}

package/dist/commands/clean.d.ts

@@ -0,0 +1,5 @@
+export interface CleanResult {
+    removed: string[];
+}
+/** Deletes exactly the files owned by the generator (manifest-listed). */
+export declare function cleanGenerated(outDir: string): CleanResult;

package/dist/commands/clean.js

@@ -0,0 +1,22 @@
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import path from 'node:path';
+const MANIFEST_NAME = 'generated.rpc-dart.json';
+/** Deletes exactly the files owned by the generator (manifest-listed). */
+export function cleanGenerated(outDir) {
+    const manifestPath = path.join(outDir, MANIFEST_NAME);
+    if (!existsSync(manifestPath)) {
+        throw new Error(`no generated manifest at ${manifestPath} - nothing owned by rpc-dart to clean`);
+    }
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    const removed = [];
+    for (const file of manifest.files) {
+        const target = path.join(outDir, file.path);
+        if (existsSync(target)) {
+            rmSync(target);
+            removed.push(file.path);
+        }
+    }
+    rmSync(manifestPath);
+    removed.push(MANIFEST_NAME);
+    return { removed };
+}

package/dist/commands/diff.d.ts

@@ -0,0 +1,26 @@
+import { type ContractIR } from '@rpc-dart/core';
+export interface DiffEntry {
+    kind: 'procedure-removed' | 'procedure-renamed' | 'procedure-added' | 'procedure-kind-changed' | 'input-field-added-required' | 'input-field-made-required' | 'input-type-changed' | 'output-field-removed' | 'output-type-changed' | 'output-nullable-changed' | 'enum-value-removed' | 'input-field-added-optional' | 'input-field-removed' | 'output-field-added' | 'enum-value-added';
+    path: string;
+    detail: string;
+    breaking: boolean;
+}
+export interface DiffResult {
+    entries: DiffEntry[];
+    breakingCount: number;
+    nonBreakingCount: number;
+    hasBreaking: boolean;
+}
+export interface DiffOptions {
+    tsconfigPath: string;
+    entryFile: string;
+    exportName: string;
+    transformer?: 'superjson' | 'json';
+    /** Path to a committed full-IR snapshot (written by --update-baseline). */
+    baselinePath: string;
+    updateBaseline?: boolean;
+}
+/** Compares the current contract against a committed IR snapshot. */
+export declare function diffContract(options: DiffOptions): Promise<DiffResult>;
+/** Structural diff between two contract IRs. */
+export declare function diffIr(baseline: ContractIR, current: ContractIR): DiffEntry[];

package/dist/commands/diff.js

@@ -0,0 +1,233 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { stableStringify } from '@rpc-dart/core';
+import { extractContract } from '@rpc-dart/trpc-adapter';
+/** Compares the current contract against a committed IR snapshot. */
+export async function diffContract(options) {
+    const { ir: current } = await extractContract({
+        tsconfigPath: options.tsconfigPath,
+        entryFile: options.entryFile,
+        exportName: options.exportName,
+        protocol: { kind: 'trpc', version: '11', transformer: options.transformer ?? 'superjson' },
+    });
+    if (options.updateBaseline || !existsSync(options.baselinePath)) {
+        if (!options.updateBaseline) {
+            throw new Error(`baseline snapshot not found at ${options.baselinePath} - run with updateBaseline to write it`);
+        }
+        writeFileSync(options.baselinePath, `${JSON.stringify(current, null, 2)}\n`);
+        return { entries: [], breakingCount: 0, nonBreakingCount: 0, hasBreaking: false };
+    }
+    const baseline = JSON.parse(readFileSync(options.baselinePath, 'utf-8'));
+    const entries = diffIr(baseline, current);
+    if (options.updateBaseline) {
+        writeFileSync(options.baselinePath, `${JSON.stringify(current, null, 2)}\n`);
+    }
+    const breakingCount = entries.filter((e) => e.breaking).length;
+    return {
+        entries,
+        breakingCount,
+        nonBreakingCount: entries.length - breakingCount,
+        hasBreaking: breakingCount > 0,
+    };
+}
+function typeSignature(type, ir, seen = new Set()) {
+    return stableStringify(stripNamesDeep(type, ir, seen));
+}
+function stripNamesDeep(type, ir, seen) {
+    switch (type.kind) {
+        case 'object':
+            return {
+                kind: 'object',
+                fields: type.fields.map((f) => ({
+                    name: f.name,
+                    type: stripRefDeep(f.type, ir, seen),
+                    optional: f.optional,
+                    nullable: f.nullable,
+                })),
+            };
+        case 'enum':
+        case 'simpleUnion':
+            return { kind: type.kind, values: type.values };
+        case 'discriminatedUnion':
+            return {
+                kind: type.kind,
+                tagField: type.tagField,
+                variants: type.variants.map((v) => ({ tag: v.tag, object: stripRefDeep(v.object, ir, seen) })),
+            };
+        case 'list':
+        case 'set':
+            return { kind: type.kind, element: stripRefDeep(type.element, ir, seen) };
+        case 'record':
+            return {
+                kind: type.kind,
+                keyType: stripRefDeep(type.keyType, ir, seen),
+                valueType: stripRefDeep(type.valueType, ir, seen),
+            };
+        case 'tuple':
+            return { kind: type.kind, items: type.items.map((t) => stripRefDeep(t, ir, seen)) };
+        case 'nullable':
+            return { kind: type.kind, inner: stripRefDeep(type.inner, ir, seen) };
+        case 'selfRef':
+            return { kind: 'selfRef' };
+        default:
+            return type;
+    }
+}
+function stripRefDeep(type, ir, seen) {
+    if (typeof type === 'string')
+        return type;
+    if ('$ref' in type) {
+        // Resolve the reference so changes INSIDE named types are visible.
+        if (seen.has(type.$ref))
+            return { $ref: 'recursive' };
+        seen.add(type.$ref);
+        const def = ir.types[type.$ref];
+        if (!def)
+            return { $ref: 'unknown' };
+        return stripNamesDeep(def, ir, seen);
+    }
+    return stripNamesDeep(type, ir, seen);
+}
+function fieldsSignature(fields) {
+    return stableStringify(fields.map((f) => ({ name: f.name, optional: f.optional, nullable: f.nullable })));
+}
+/** Structural diff between two contract IRs. */
+export function diffIr(baseline, current) {
+    const entries = [];
+    const baselinePaths = Object.keys(baseline.procedures).sort();
+    const currentPaths = Object.keys(current.procedures).sort();
+    // Rename detection: removed procedures whose shape reappears under a new path.
+    const removed = baselinePaths.filter((p) => !currentPaths.includes(p));
+    const added = currentPaths.filter((p) => !baselinePaths.includes(p));
+    const consumedAdded = new Set();
+    for (const path of removed) {
+        const oldRecord = baseline.procedures[path];
+        const renamedTo = added.find((candidate) => {
+            if (consumedAdded.has(candidate))
+                return false;
+            const newRecord = current.procedures[candidate];
+            return (newRecord.kind === oldRecord.kind &&
+                typeSignature(resolveOutput(oldRecord.output, baseline), baseline) ===
+                    typeSignature(resolveOutput(newRecord.output, current), current) &&
+                fieldsSignature(oldRecord.input === null ? [] : resolveInputFields(oldRecord.input, baseline)) ===
+                    fieldsSignature(newRecord.input === null ? [] : resolveInputFields(newRecord.input, current)));
+        });
+        if (renamedTo) {
+            consumedAdded.add(renamedTo);
+            entries.push({
+                kind: 'procedure-renamed',
+                path,
+                detail: `renamed to ${renamedTo}`,
+                breaking: true,
+            });
+        }
+        else {
+            entries.push({ kind: 'procedure-removed', path, detail: 'removed', breaking: true });
+        }
+    }
+    for (const path of added) {
+        if (consumedAdded.has(path))
+            continue;
+        entries.push({ kind: 'procedure-added', path, detail: 'added', breaking: false });
+    }
+    for (const path of baselinePaths.filter((p) => currentPaths.includes(p))) {
+        const before = baseline.procedures[path];
+        const after = current.procedures[path];
+        if (before.kind !== after.kind) {
+            entries.push({ kind: 'procedure-kind-changed', path, detail: `${before.kind} -> ${after.kind}`, breaking: true });
+            continue;
+        }
+        const beforeInput = before.input === null ? null : resolveInputFields(before.input, baseline);
+        const afterInput = after.input === null ? null : resolveInputFields(after.input, current);
+        if ((beforeInput === null) !== (afterInput === null)) {
+            entries.push({
+                kind: 'input-type-changed',
+                path,
+                detail: 'input presence changed',
+                breaking: true,
+            });
+        }
+        else if (beforeInput && afterInput) {
+            diffInputFields(path, beforeInput, afterInput, entries, baseline, current);
+        }
+        const beforeOutput = resolveOutput(before.output, baseline);
+        const afterOutput = resolveOutput(after.output, current);
+        if (typeSignature(beforeOutput, baseline) !== typeSignature(afterOutput, current)) {
+            diffOutputFields(path, beforeOutput, afterOutput, entries, baseline, current);
+        }
+    }
+    return entries;
+}
+function resolveInputFields(input, ir) {
+    const def = resolveDef(input, ir);
+    if (def.kind !== 'object')
+        return [];
+    return def.fields;
+}
+function resolveOutput(output, ir) {
+    return resolveDef(output, ir);
+}
+function resolveDef(type, ir) {
+    if (typeof type === 'string') {
+        return { kind: 'primitive', name: type };
+    }
+    if ('$ref' in type) {
+        const def = ir.types[type.$ref];
+        if (!def)
+            throw new Error(`missing registry entry ${type.$ref}`);
+        return def;
+    }
+    return type;
+}
+function diffInputFields(path, before, after, entries, baseline, current) {
+    const beforeByName = new Map(before.map((f) => [f.name, f]));
+    const afterByName = new Map(after.map((f) => [f.name, f]));
+    for (const [name, beforeField] of beforeByName) {
+        const afterField = afterByName.get(name);
+        if (!afterField) {
+            entries.push({ kind: 'input-field-removed', path: `${path}#${name}`, detail: 'input field removed', breaking: false });
+            continue;
+        }
+        if (!beforeField.optional && afterField.optional) {
+            entries.push({ kind: 'input-field-made-required', path: `${path}#${name}`, detail: 'optional -> required', breaking: true });
+        }
+        if (typeSignature(beforeField.type, baseline) !== typeSignature(afterField.type, current)) {
+            entries.push({ kind: 'input-type-changed', path: `${path}#${name}`, detail: 'input field type changed', breaking: true });
+        }
+    }
+    for (const [name, afterField] of afterByName) {
+        if (!beforeByName.has(name)) {
+            entries.push({
+                kind: afterField.optional ? 'input-field-added-optional' : 'input-field-added-required',
+                path: `${path}#${name}`,
+                detail: afterField.optional ? 'optional input field added' : 'required input field added',
+                breaking: !afterField.optional,
+            });
+        }
+    }
+}
+function diffOutputFields(path, before, after, entries, baseline, current) {
+    if (before.kind !== 'object' || after.kind !== 'object') {
+        entries.push({ kind: 'output-type-changed', path, detail: `output type changed (${before.kind} -> ${after.kind})`, breaking: true });
+        return;
+    }
+    const beforeByName = new Map(before.fields.map((f) => [f.name, f]));
+    const afterByName = new Map(after.fields.map((f) => [f.name, f]));
+    for (const [name, beforeField] of beforeByName) {
+        const afterField = afterByName.get(name);
+        if (!afterField) {
+            entries.push({ kind: 'output-field-removed', path: `${path}#${name}`, detail: 'output field removed', breaking: true });
+            continue;
+        }
+        if (beforeField.nullable !== afterField.nullable) {
+            entries.push({ kind: 'output-nullable-changed', path: `${path}#${name}`, detail: 'output nullability changed', breaking: true });
+        }
+        if (typeSignature(beforeField.type, baseline) !== typeSignature(afterField.type, current)) {
+            entries.push({ kind: 'output-type-changed', path: `${path}#${name}`, detail: 'output field type changed', breaking: true });
+        }
+    }
+    for (const name of afterByName.keys()) {
+        if (!beforeByName.has(name)) {
+            entries.push({ kind: 'output-field-added', path: `${path}#${name}`, detail: 'output field added', breaking: false });
+        }
+    }
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,14 @@
+export interface DoctorCheck {
+    name: string;
+    status: 'pass' | 'warn' | 'fail';
+    detail: string;
+}
+export interface DoctorOptions {
+    tsconfigPath?: string;
+    entryFile?: string;
+    exportName?: string;
+    /** Path to a Dart package whose pubspec version should match the CLI's. */
+    dartPackagePath?: string;
+}
+/** Environment + workspace checklist. */
+export declare function doctorChecks(options?: DoctorOptions): Promise<DoctorCheck[]>;

package/dist/commands/doctor.js

@@ -0,0 +1,94 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { extractContract } from '@rpc-dart/trpc-adapter';
+/** Environment + workspace checklist. */
+export async function doctorChecks(options = {}) {
+    const checks = [];
+    const nodeMajor = Number(process.versions.node.split('.')[0]);
+    checks.push({
+        name: 'node-version',
+        status: nodeMajor >= 20 ? 'pass' : 'fail',
+        detail: `node ${process.versions.node} (requires >= 20)`,
+    });
+    if (options.tsconfigPath) {
+        checks.push({
+            name: 'tsconfig',
+            status: existsSync(options.tsconfigPath) ? 'pass' : 'fail',
+            detail: options.tsconfigPath,
+        });
+    }
+    else {
+        checks.push({ name: 'tsconfig', status: 'warn', detail: 'no tsconfig path provided' });
+    }
+    if (options.entryFile && options.exportName) {
+        try {
+            await extractContract({
+                tsconfigPath: options.tsconfigPath ?? '',
+                entryFile: options.entryFile,
+                exportName: options.exportName,
+                protocol: { kind: 'trpc', version: '11', transformer: 'superjson' },
+            });
+            checks.push({ name: 'router-export', status: 'pass', detail: `${options.exportName} extracted` });
+        }
+        catch (error) {
+            checks.push({
+                name: 'router-export',
+                status: 'fail',
+                detail: error.message.slice(0, 200),
+            });
+        }
+    }
+    else {
+        checks.push({ name: 'router-export', status: 'warn', detail: 'no router configured yet (run rpc-dart init)' });
+    }
+    let dartBin = null;
+    for (const candidate of [process.env.DART_BIN, 'dart', `${process.env.HOME}/development/flutter/bin/dart`]) {
+        if (!candidate)
+            continue;
+        try {
+            execFileSync(candidate, ['--version'], { stdio: 'pipe' });
+            dartBin = candidate;
+            break;
+        }
+        catch {
+            continue;
+        }
+    }
+    checks.push({
+        name: 'dart-sdk',
+        status: dartBin ? 'pass' : 'fail',
+        detail: dartBin ?? 'dart not found on PATH (set DART_BIN)',
+    });
+    try {
+        execFileSync('flutter', ['--version', '--machine'], { stdio: 'pipe' });
+        checks.push({ name: 'flutter-sdk', status: 'pass', detail: 'flutter available' });
+    }
+    catch {
+        checks.push({ name: 'flutter-sdk', status: 'warn', detail: 'flutter not available (optional for server-only use)' });
+    }
+    if (options.dartPackagePath) {
+        const pubspecPath = `${options.dartPackagePath}/pubspec.yaml`;
+        try {
+            const pubspec = readFileSync(pubspecPath, 'utf-8');
+            const dartVersion = /^version:\s*(.+)$/m.exec(pubspec)?.[1]?.trim();
+            const cliPackage = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf-8'));
+            const cliVersion = cliPackage.version ?? 'unknown';
+            checks.push({
+                name: 'version-alignment',
+                status: dartVersion === cliVersion ? 'pass' : 'warn',
+                detail: `rpc-dart ${cliVersion} vs runtime ${dartVersion ?? 'unknown'}`,
+            });
+        }
+        catch (error) {
+            checks.push({
+                name: 'version-alignment',
+                status: 'warn',
+                detail: `could not read pubspec: ${error.message.slice(0, 120)}`,
+            });
+        }
+    }
+    else {
+        checks.push({ name: 'version-alignment', status: 'warn', detail: 'no dart package path provided' });
+    }
+    return checks;
+}

package/dist/commands/generate.d.ts

@@ -0,0 +1,22 @@
+export interface GenerateOptions {
+    tsconfigPath: string;
+    entryFile: string;
+    exportName: string;
+    /** Generated root, e.g. <consumer>/lib/src/api */
+    outDir: string;
+    transformer?: 'superjson' | 'json';
+    force?: boolean;
+    policies?: {
+        unserializablePolicy?: 'error' | 'warn-dynamic' | 'skip-procedure';
+    };
+}
+export interface GenerateResult {
+    files: string[];
+    hash: string;
+    wrote: boolean;
+}
+/**
+ * Full pipeline: extract -> hash gate -> emit -> atomic writes -> manifest ->
+ * stale-file cleanup.
+ */
+export declare function generate(options: GenerateOptions): Promise<GenerateResult>;

package/dist/commands/generate.js

@@ -0,0 +1,73 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { extractContract } from '@rpc-dart/trpc-adapter';
+import { emit } from '@rpc-dart/dart-generator';
+const MANIFEST_NAME = 'generated.rpc-dart.json';
+/**
+ * Full pipeline: extract -> hash gate -> emit -> atomic writes -> manifest ->
+ * stale-file cleanup.
+ */
+export async function generate(options) {
+    const { ir, diagnostics } = await extractContract({
+        tsconfigPath: options.tsconfigPath,
+        entryFile: options.entryFile,
+        exportName: options.exportName,
+        protocol: { kind: 'trpc', version: '11', transformer: options.transformer ?? 'superjson' },
+        policies: options.policies,
+    });
+    const manifestPath = path.join(options.outDir, MANIFEST_NAME);
+    const previous = existsSync(manifestPath)
+        ? JSON.parse(readFileSync(manifestPath, 'utf-8'))
+        : null;
+    if (previous && previous.irHash === ir.hash && !options.force) {
+        return {
+            files: previous.files.map((f) => f.path),
+            hash: ir.hash,
+            wrote: false,
+        };
+    }
+    const emitted = emit(ir);
+    // emit() lays out under lib/src/api/; the consumer's outDir IS that root.
+    // Manifest paths are normalized too so stale cleanup addresses real files.
+    const manifestRaw = JSON.parse(emitted.files['lib/src/api/generated.rpc-dart.json']);
+    manifestRaw.files = manifestRaw.files.map((f) => ({
+        path: f.path.replace(/^lib\/src\/api\//, ''),
+        contentSha256: f.contentSha256,
+    }));
+    manifestRaw.diagnostics = diagnostics;
+    manifestRaw.policies = options.policies ?? { unserializablePolicy: 'error' };
+    const files = {};
+    for (const [rel, content] of Object.entries(emitted.files)) {
+        const stripped = rel.replace(/^lib\/src\/api\//, '');
+        files[stripped] = rel === 'lib/src/api/generated.rpc-dart.json'
+            ? `${JSON.stringify(manifestRaw, null, 2)}\n`
+            : content;
+    }
+    const written = [];
+    for (const [rel, content] of Object.entries(files)) {
+        const target = path.join(options.outDir, rel);
+        mkdirSync(path.dirname(target), { recursive: true });
+        const tmp = `${target}.tmp`;
+        writeFileSync(tmp, content);
+        renameSync(tmp, target);
+        written.push(rel);
+    }
+    // Stale cleanup: committed files from the previous manifest that the new
+    // emission no longer contains (crash-safe: cleanup happens after a
+    // successful full write, manifest last).
+    if (previous) {
+        for (const prevFile of previous.files) {
+            if (!(prevFile.path in files)) {
+                const stalePath = path.join(options.outDir, prevFile.path);
+                if (existsSync(stalePath)) {
+                    rmLocal(stalePath);
+                }
+            }
+        }
+    }
+    return { files: written, hash: ir.hash, wrote: true };
+}
+import { rmSync } from 'node:fs';
+function rmLocal(target) {
+    rmSync(target);
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,29 @@
+export interface InitOptions {
+    /** Additional Flutter target directories to consider. */
+    flutterDirs?: string[];
+    /** Skip detection and write explicit values (used by tests). */
+    entryFile?: string;
+    exportName?: string;
+}
+export interface InitResult {
+    configPath: string;
+    config: {
+        entry: string;
+        exportName: string;
+        transformer: 'superjson' | 'json';
+        dart: {
+            outDir: string;
+            packagePath?: string;
+        };
+        policies: {
+            unserializablePolicy: 'error' | 'warn-dynamic' | 'skip-procedure';
+        };
+    };
+    detected: {
+        tsconfig: string | null;
+        routerCandidates: string[];
+        flutterDirs: string[];
+    };
+}
+/** Detects workspace shape and scaffolds rpc-dart.config.ts. Idempotent-guarded. */
+export declare function initWorkspace(workspaceDir: string, options?: InitOptions): Promise<InitResult>;

package/dist/commands/init.js

@@ -0,0 +1,113 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+const CONFIG_FILE = 'rpc-dart.config.ts';
+/** Detects workspace shape and scaffolds rpc-dart.config.ts. Idempotent-guarded. */
+export async function initWorkspace(workspaceDir, options = {}) {
+    const configPath = path.join(workspaceDir, CONFIG_FILE);
+    if (existsSync(configPath)) {
+        throw new Error(`${CONFIG_FILE} already exists at ${configPath} - refusing to overwrite`);
+    }
+    const detected = { tsconfig: null, routerCandidates: [], flutterDirs: [] };
+    const tsconfigPath = path.join(workspaceDir, 'tsconfig.json');
+    if (existsSync(tsconfigPath)) {
+        detected.tsconfig = 'tsconfig.json';
+    }
+    const routerCandidates = findRouterCandidates(workspaceDir);
+    detected.routerCandidates = routerCandidates;
+    const flutterDirs = findFlutterDirs(workspaceDir, options.flutterDirs ?? []);
+    detected.flutterDirs = flutterDirs;
+    const entryFile = options.entryFile ??
+        (routerCandidates.length > 0 ? path.relative(workspaceDir, routerCandidates[0]) : 'src/trpc/router.ts');
+    const entryText = existsSync(path.join(workspaceDir, entryFile))
+        ? readFileSync(path.join(workspaceDir, entryFile), 'utf-8')
+        : '';
+    const exportName = options.exportName ??
+        (/export\s+(?:const|type)\s+(appRouter|router|trpcRouter)\b/.exec(entryText)?.[1] ??
+            /export\s+const\s+(\w+Router)\b/.exec(entryText)?.[1] ??
+            'appRouter');
+    const flutterTarget = flutterDirs[0];
+    const config = {
+        entry: entryFile,
+        exportName,
+        transformer: 'superjson',
+        dart: {
+            outDir: flutterTarget
+                ? path.join(path.relative(workspaceDir, flutterTarget), 'lib/src/api')
+                : 'lib/src/api',
+            packagePath: flutterTarget ? path.relative(workspaceDir, flutterTarget) : undefined,
+        },
+        policies: { unserializablePolicy: 'error' },
+    };
+    writeFileSync(configPath, `import { defineConfig } from 'rpc-dart';
+
+// Generated by rpc-dart init. Review the detected values below.
+export default defineConfig({
+  entry: ${JSON.stringify(config.entry)},
+  exportName: ${JSON.stringify(config.exportName)},
+  transformer: ${JSON.stringify(config.transformer)},
+  dart: {
+    outDir: ${JSON.stringify(config.dart.outDir)},
+    packagePath: ${config.dart.packagePath ? JSON.stringify(config.dart.packagePath) : 'undefined'},
+  },
+  policies: {
+    unserializablePolicy: ${JSON.stringify(config.policies.unserializablePolicy)},
+  },
+});
+`);
+    return { configPath, config, detected };
+}
+function findRouterCandidates(workspaceDir) {
+    const candidates = [];
+    const scan = (dir, depth) => {
+        if (depth > 4 || candidates.length >= 5)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name === 'node_modules' || entry.name.startsWith('.'))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                scan(full, depth + 1);
+            }
+            else if (/(^|\/)(router|trpc|app)\.tsx?$/.test(entry.name) ||
+                entry.name.endsWith('Router.ts')) {
+                try {
+                    const text = readFileSync(full, 'utf-8');
+                    if (text.includes('initTRPC')) {
+                        candidates.push(full);
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+    };
+    scan(workspaceDir, 0);
+    return candidates;
+}
+function findFlutterDirs(workspaceDir, extra) {
+    const found = [];
+    for (const dir of [...readdirSafe(workspaceDir).map((n) => path.join(workspaceDir, n)), ...extra]) {
+        if (existsSync(path.join(dir, 'pubspec.yaml'))) {
+            found.push(dir);
+        }
+    }
+    return found;
+}
+function readdirSafe(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && e.name !== 'node_modules' && !e.name.startsWith('.'))
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/commands/watch.d.ts

@@ -0,0 +1,25 @@
+import { type GenerateOptions } from './generate.js';
+export interface WatchCycle {
+    changed: boolean;
+    durationMs: number;
+    hash: string;
+    written: number;
+}
+export interface WatchSessionOptions extends GenerateOptions {
+    debounceMs?: number;
+    onCycle?: (cycle: WatchCycle) => void;
+    onError?: (error: Error) => void;
+}
+export declare class WatchSession {
+    private readonly options;
+    private readonly watchers;
+    private timer;
+    private stopped;
+    private running;
+    private lastHash;
+    constructor(options: WatchSessionOptions);
+    start(): void;
+    stop(): void;
+    private schedule;
+    private cycle;
+}

package/dist/commands/watch.js

@@ -0,0 +1,91 @@
+import { watch } from 'node:fs';
+import { extractContract } from '@rpc-dart/trpc-adapter';
+import { generate } from './generate.js';
+export class WatchSession {
+    options;
+    watchers = [];
+    timer = null;
+    stopped = false;
+    running = false;
+    lastHash = null;
+    constructor(options) {
+        this.options = options;
+    }
+    start() {
+        this.stopped = false;
+        const watchDirs = new Set([
+            path.dirname(this.options.entryFile),
+            path.dirname(this.options.tsconfigPath),
+        ]);
+        for (const dir of watchDirs) {
+            try {
+                const watcher = watch(dir, { recursive: true }, () => this.schedule());
+                this.watchers.push(watcher);
+            }
+            catch {
+                // Directory may not exist yet; the initial cycle still runs.
+            }
+        }
+        void this.cycle();
+    }
+    stop() {
+        this.stopped = true;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        for (const watcher of this.watchers) {
+            watcher.close();
+        }
+        this.watchers.length = 0;
+    }
+    schedule() {
+        if (this.stopped)
+            return;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            void this.cycle();
+        }, this.options.debounceMs ?? 300);
+    }
+    async cycle() {
+        if (this.stopped || this.running)
+            return;
+        this.running = true;
+        const started = Date.now();
+        try {
+            const { ir } = await extractContract({
+                tsconfigPath: this.options.tsconfigPath,
+                entryFile: this.options.entryFile,
+                exportName: this.options.exportName,
+                protocol: { kind: 'trpc', version: '11', transformer: this.options.transformer ?? 'superjson' },
+                policies: this.options.policies,
+            });
+            if (this.lastHash !== null && ir.hash === this.lastHash) {
+                this.options.onCycle?.({
+                    changed: false,
+                    durationMs: Date.now() - started,
+                    hash: ir.hash,
+                    written: 0,
+                });
+                return;
+            }
+            const result = await generate(this.options);
+            this.lastHash = result.hash;
+            this.options.onCycle?.({
+                changed: result.wrote,
+                durationMs: Date.now() - started,
+                hash: result.hash,
+                written: result.files.length,
+            });
+        }
+        catch (error) {
+            this.options.onError?.(error);
+        }
+        finally {
+            this.running = false;
+        }
+    }
+}
+import path from 'node:path';

package/dist/config.d.ts

@@ -0,0 +1,42 @@
+export interface RpcDartTarget {
+    name?: string;
+    /** Path to tsconfig.json, relative to the config file's directory. */
+    tsconfig?: string;
+    entry: string;
+    exportName: string;
+    transformer?: 'superjson' | 'json';
+    dart?: {
+        outDir: string;
+        packagePath?: string;
+    };
+    policies?: {
+        unserializablePolicy?: 'error' | 'warn-dynamic' | 'skip-procedure';
+    };
+}
+export interface RpcDartConfig extends RpcDartTarget {
+    /** Multiple generation targets; each gets its own outDir. */
+    projects?: RpcDartTarget[];
+}
+export type RpcDartConfigFile = 'rpc-dart.config.json' | 'rpc-dart.config.ts';
+export declare function defineConfig(config: RpcDartConfig): RpcDartConfig;
+/** Raised when no usable configuration can be discovered. Exit code 2. */
+export declare class ConfigNotFoundError extends Error {
+    readonly searchDir: string;
+    constructor(searchDir: string);
+}
+export declare function findConfigFile(searchDir: string, explicit?: string): string | null;
+export declare function loadConfigFileAsync(configPath: string): Promise<RpcDartConfig>;
+/**
+ * Resolves the concrete generation targets from CLI flags + config file.
+ * Explicit flags override config values. Supports multi-project configs.
+ */
+export declare function resolveTargets(searchDir: string, flags: {
+    config?: string;
+    tsconfig?: string;
+    entry?: string;
+    exportName?: string;
+    out?: string;
+    transformer?: string;
+}): Promise<Array<RpcDartTarget & {
+    tsconfigPath: string;
+}>>;

package/dist/config.js

@@ -0,0 +1,81 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createJiti } from 'jiti';
+export function defineConfig(config) {
+    return config;
+}
+/** Raised when no usable configuration can be discovered. Exit code 2. */
+export class ConfigNotFoundError extends Error {
+    searchDir;
+    constructor(searchDir) {
+        super(`no rpc-dart.config.json found in ${searchDir} (or any flags provided).\n` +
+            '  Run `npx rpc-dart init` to create one, or pass --config / --tsconfig / --entry / --export / --out.');
+        this.searchDir = searchDir;
+        this.name = 'ConfigNotFoundError';
+    }
+}
+export function findConfigFile(searchDir, explicit) {
+    if (explicit) {
+        const resolved = path.resolve(searchDir, explicit);
+        return existsSync(resolved) ? resolved : null;
+    }
+    for (const name of ['rpc-dart.config.json', 'rpc-dart.config.ts']) {
+        const candidate = path.join(searchDir, name);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+export async function loadConfigFileAsync(configPath) {
+    if (configPath.endsWith('.json')) {
+        return JSON.parse(readFileSync(configPath, 'utf-8'));
+    }
+    const jiti = createJiti(configPath, { fsCache: false, moduleCache: false });
+    const mod = (await jiti.import(configPath));
+    if (!mod.default) {
+        throw new Error(`${configPath} must default-export a defineConfig() value`);
+    }
+    return mod.default;
+}
+/**
+ * Resolves the concrete generation targets from CLI flags + config file.
+ * Explicit flags override config values. Supports multi-project configs.
+ */
+export async function resolveTargets(searchDir, flags) {
+    const configPath = findConfigFile(searchDir, flags.config);
+    let config = null;
+    if (configPath) {
+        config = await loadConfigFileAsync(configPath);
+    }
+    // Flags-only mode when no config exists. Entry resolves against the
+    // tsconfig's directory (matching extraction semantics).
+    if (!config) {
+        if (flags.tsconfig && flags.entry && flags.exportName && flags.out) {
+            const tsconfigPath = path.resolve(searchDir, flags.tsconfig);
+            return [
+                {
+                    entry: path.resolve(path.dirname(tsconfigPath), flags.entry),
+                    exportName: flags.exportName,
+                    transformer: flags.transformer ?? 'superjson',
+                    dart: { outDir: flags.out },
+                    tsconfigPath,
+                },
+            ];
+        }
+        throw new ConfigNotFoundError(searchDir);
+    }
+    const configDir = path.dirname(configPath);
+    const projects = config.projects && config.projects.length > 0 ? config.projects : [config];
+    return projects.map((project) => ({
+        ...project,
+        entry: path.resolve(configDir, flags.entry ?? project.entry),
+        exportName: flags.exportName ?? project.exportName,
+        transformer: flags.transformer ?? project.transformer,
+        dart: {
+            ...project.dart,
+            outDir: flags.out ?? project.dart?.outDir ?? 'lib/src/api',
+        },
+        policies: project.policies,
+        tsconfigPath: path.resolve(path.dirname(configPath ?? searchDir), flags.tsconfig ?? project.tsconfig ?? 'tsconfig.json'),
+    }));
+}
+import path from 'node:path';

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { generate, type GenerateOptions, type GenerateResult } from './commands/generate.js';
+export { checkContract, type CheckResult } from './commands/check.js';
+export { diffContract, diffIr, type DiffEntry, type DiffOptions, type DiffResult, } from './commands/diff.js';
+export { cleanGenerated, type CleanResult } from './commands/clean.js';
+export { doctorChecks, type DoctorCheck, type DoctorOptions } from './commands/doctor.js';
+export { initWorkspace, type InitOptions, type InitResult } from './commands/init.js';
+export { WatchSession, type WatchCycle, type WatchSessionOptions } from './commands/watch.js';
+export { ConfigNotFoundError, defineConfig, findConfigFile, loadConfigFileAsync as loadConfig, resolveTargets, type RpcDartConfig, type RpcDartTarget, } from './config.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { generate } from './commands/generate.js';
+export { checkContract } from './commands/check.js';
+export { diffContract, diffIr, } from './commands/diff.js';
+export { cleanGenerated } from './commands/clean.js';
+export { doctorChecks } from './commands/doctor.js';
+export { initWorkspace } from './commands/init.js';
+export { WatchSession } from './commands/watch.js';
+export { ConfigNotFoundError, defineConfig, findConfigFile, loadConfigFileAsync as loadConfig, resolveTargets, } from './config.js';

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "rpc-dart",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.2",
+  "description": "TypeScript-to-Dart bindings generator for tRPC v11 backends.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "rpc-dart": "bin/rpc-dart.js"
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "dependencies": {
+    "@rpc-dart/core": "0.1.2",
+    "@rpc-dart/trpc-adapter": "0.1.2",
+    "@rpc-dart/dart-generator": "0.1.2",
+    "jiti": "^2.6.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0",
+    "@types/node": "^24.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AdityaJandu/rpc-dart.git"
+  },
+  "homepage": "https://github.com/AdityaJandu/rpc-dart#readme",
+  "keywords": [
+    "trpc",
+    "dart",
+    "flutter",
+    "cli",
+    "codegen"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
 }