@contractkit/plugin-typescript 0.26.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractkit/plugin-typescript",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "ContractKit built-in plugin: TypeScript codegen (SDK clients, Koa routers, Zod schemas, plain types)",
   "author": {
     "name": "Marooned Software",
@@ -26,7 +26,7 @@
     ".": "./dist/index.js"
   },
   "dependencies": {
-    "@contractkit/core": "0.21.0"
+    "@contractkit/core": "0.22.0"
   },
   "devDependencies": {
     "@repo/config-typescript": "0.1.0",

package/src/codegen-sdk.ts

@@ -959,6 +959,84 @@ export function generateSdkOptions(): string {
     ].join('\n');
 }
 
+// ─── Scaffold files (package.json / tsconfig.json) ─────────────────────────
+
+/** Pinned dependency ranges for scaffolded SDK packages. Kept in one place so they're easy to bump. */
+const SCAFFOLD_DEP_VERSIONS = {
+    zod: '^4.3.6',
+    luxon: '^3.5.0',
+    typesLuxon: '^3.4.2',
+    typescript: '^6.0.3',
+} as const;
+
+/** Which optional runtime deps the generated SDK references, derived from the contracts it covers. */
+export interface SdkScaffoldDeps {
+    /** Zod schema files are emitted (`config.zod`) — the SDK imports `zod`. */
+    zod: boolean;
+    /** Any covered model uses a `date`/`time`/`datetime`/`interval` scalar — the SDK imports `luxon`. */
+    luxon: boolean;
+}
+
+/**
+ * Generate a starter `package.json` for a generated SDK package. Emitted with
+ * `ifAbsent` semantics — written once, then owned by the user — so the dependency
+ * ranges here are only ever a starting point, never re-applied on later builds.
+ */
+export function generateSdkPackageJson(input: { name: string; deps: SdkScaffoldDeps }): string {
+    const dependencies: Record<string, string> = {};
+    if (input.deps.zod) dependencies.zod = SCAFFOLD_DEP_VERSIONS.zod;
+    if (input.deps.luxon) dependencies.luxon = SCAFFOLD_DEP_VERSIONS.luxon;
+
+    const devDependencies: Record<string, string> = { typescript: SCAFFOLD_DEP_VERSIONS.typescript };
+    if (input.deps.luxon) devDependencies['@types/luxon'] = SCAFFOLD_DEP_VERSIONS.typesLuxon;
+
+    const pkg = {
+        name: input.name,
+        version: '0.0.0',
+        type: 'module',
+        main: './dist/index.js',
+        types: './dist/index.d.ts',
+        exports: {
+            '.': {
+                types: './dist/index.d.ts',
+                import: './dist/index.js',
+            },
+        },
+        files: ['dist'],
+        scripts: {
+            build: 'tsc -p tsconfig.json',
+        },
+        ...(Object.keys(dependencies).length > 0 ? { dependencies } : {}),
+        devDependencies,
+    };
+    return JSON.stringify(pkg, null, 4) + '\n';
+}
+
+/**
+ * Generate a standalone `tsconfig.json` for a generated SDK package. Deliberately
+ * self-contained (no workspace `extends`) so the scaffold works in a freshly
+ * `npm init`'d package outside this monorepo. Emitted with `ifAbsent` semantics.
+ */
+export function generateSdkTsconfig(): string {
+    const tsconfig = {
+        compilerOptions: {
+            target: 'ES2022',
+            module: 'NodeNext',
+            moduleResolution: 'NodeNext',
+            declaration: true,
+            outDir: './dist',
+            rootDir: './src',
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+            forceConsistentCasingInFileNames: true,
+        },
+        include: ['src'],
+        exclude: ['dist', 'node_modules'],
+    };
+    return JSON.stringify(tsconfig, null, 4) + '\n';
+}
+
 /**
  * Reference to a per-file leaf client emitted to its own `*.client.ts`. Used by the
  * aggregator to import the class and wire it as either a top-level `sdk.<prop>` or a

package/src/index.ts

@@ -1,6 +1,6 @@
 import { resolve, join, relative, dirname, basename } from 'node:path';
 import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, readdirSync, rmdirSync } from 'node:fs';
-import { generateContract } from './codegen-contract.js';
+import { generateContract, rootNeedsScalar } from './codegen-contract.js';
 import { generateOp } from './codegen-operation.js';
 import type {
     ContractKitPlugin,
@@ -34,8 +34,11 @@ import {
     deriveSubareaPropertyName,
     getAreaSubarea,
     hasPublicOperations,
+    generateSdkPackageJson,
+    generateSdkTsconfig,
     type SdkClientInfo,
     type SdkAreaInfo,
+    type SdkScaffoldDeps,
 } from './codegen-sdk.js';
 import { generatePlainTypes } from './codegen-plain-types.js';
 import {
@@ -80,6 +83,15 @@ export interface SdkConfig {
         clients?: string;
     };
     includeInternal?: boolean;
+    /**
+     * Emit a starter `package.json` and `tsconfig.json` at the SDK `baseDir` so the
+     * generated output is a buildable, publishable package on its own. Opt-in and
+     * write-once: the files are created only when absent and are never overwritten or
+     * cleaned up on later builds, so any edits you make to them are preserved.
+     * Dependency ranges are derived from the contracts (always `zod` when `zod: true`;
+     * `luxon` when any covered model uses a date/time/datetime/interval scalar).
+     */
+    scaffold?: boolean;
 }
 
 export interface ZodConfig {
@@ -165,8 +177,8 @@ async function runTypescriptCodegen(
 
     deleteStalePaths(result.deletedPaths);
 
-    for (const { relativePath, content } of result.filesToWrite) {
-        ctx.emitFile(relativePath, content);
+    for (const { relativePath, content, ifAbsent } of result.filesToWrite) {
+        ctx.emitFile(relativePath, content, ifAbsent ? { ifAbsent: true } : undefined);
     }
 
     writeManifest(manifestPath, result.manifest);
@@ -691,6 +703,31 @@ function collectSdkOutput(
         relativePath: join(sdkSrcDir, 'index.ts'),
         content: `// Auto-generated barrel file\n${rootExports.sort().join('\n')}\n`,
     });
+
+    // ── Scaffold files (opt-in, write-once) ──
+    // Emitted at the SDK package root with `ifAbsent` so they're created once and
+    // then owned by the user. Deps are derived from the contracts actually surfaced
+    // into the SDK: zod when schema output is on, luxon when any covered model uses a
+    // date/time/datetime/interval scalar.
+    if (config.scaffold) {
+        const coveredRoots = sdkContractEntries.map(e => e.ast);
+        const deps: SdkScaffoldDeps = {
+            zod: !!config.zod,
+            luxon: coveredRoots.some(
+                r => rootNeedsScalar(r, 'datetime') || rootNeedsScalar(r, 'date') || rootNeedsScalar(r, 'time') || rootNeedsScalar(r, 'interval'),
+            ),
+        };
+        globalFiles.push({
+            relativePath: join(sdkBase, 'package.json'),
+            content: generateSdkPackageJson({ name: sdkName ?? 'sdk', deps }),
+            ifAbsent: true,
+        });
+        globalFiles.push({
+            relativePath: join(sdkBase, 'tsconfig.json'),
+            content: generateSdkTsconfig(),
+            ifAbsent: true,
+        });
+    }
 }
 
 // ─── Zod sub-generator ─────────────────────────────────────────────────────

package/tests/codegen-sdk.test.ts

@@ -12,6 +12,8 @@ import {
     deriveSubareaPropertyName,
     getAreaSubarea,
     hasPublicOperations,
+    generateSdkPackageJson,
+    generateSdkTsconfig,
 } from '../src/codegen-sdk.js';
 import { collectPublicTypeNames } from '@contractkit/core';
 import { renderTsType, renderInputTsType } from '../src/ts-render.js';
@@ -1668,3 +1670,49 @@ describe('generateAreaClient — <Area>Client emission', () => {
         ).toThrow(/duplicate method 'getCurrentUser' in area 'identity'/);
     });
 });
+
+describe('generateSdkPackageJson', () => {
+    it('emits a valid package.json with the given name and standard fields', () => {
+        const pkg = JSON.parse(generateSdkPackageJson({ name: 'my-sdk', deps: { zod: false, luxon: false } }));
+        expect(pkg.name).toBe('my-sdk');
+        expect(pkg.type).toBe('module');
+        expect(pkg.exports['.'].types).toBe('./dist/index.d.ts');
+        expect(pkg.scripts.build).toContain('tsc');
+        expect(pkg.devDependencies.typescript).toBeDefined();
+    });
+
+    it('omits the dependencies block entirely when neither zod nor luxon is used', () => {
+        const pkg = JSON.parse(generateSdkPackageJson({ name: 'sdk', deps: { zod: false, luxon: false } }));
+        expect(pkg.dependencies).toBeUndefined();
+        expect(pkg.devDependencies['@types/luxon']).toBeUndefined();
+    });
+
+    it('adds zod as a runtime dependency when zod output is enabled', () => {
+        const pkg = JSON.parse(generateSdkPackageJson({ name: 'sdk', deps: { zod: true, luxon: false } }));
+        expect(pkg.dependencies.zod).toBeDefined();
+        expect(pkg.dependencies.luxon).toBeUndefined();
+    });
+
+    it('adds luxon (runtime) and @types/luxon (dev) when a date/time scalar is used', () => {
+        const pkg = JSON.parse(generateSdkPackageJson({ name: 'sdk', deps: { zod: false, luxon: true } }));
+        expect(pkg.dependencies.luxon).toBeDefined();
+        expect(pkg.devDependencies['@types/luxon']).toBeDefined();
+    });
+
+    it('ends with a trailing newline', () => {
+        expect(generateSdkPackageJson({ name: 'sdk', deps: { zod: false, luxon: false } }).endsWith('}\n')).toBe(true);
+    });
+});
+
+describe('generateSdkTsconfig', () => {
+    it('emits a self-contained tsconfig with no workspace extends', () => {
+        const raw = generateSdkTsconfig();
+        const cfg = JSON.parse(raw);
+        expect(cfg.extends).toBeUndefined();
+        expect(cfg.compilerOptions.declaration).toBe(true);
+        expect(cfg.compilerOptions.outDir).toBe('./dist');
+        expect(cfg.compilerOptions.strict).toBe(true);
+        expect(cfg.include).toEqual(['src']);
+        expect(raw.endsWith('}\n')).toBe(true);
+    });
+});

package/tests/codegen-server.test.ts

@@ -303,3 +303,110 @@ describe('createTypescriptPlugin (sdk) — area / subarea grouping', () => {
         expect(sdk).not.toMatch(/class \w+Client \{/m);
     });
 });
+
+describe('createTypescriptPlugin (sdk) — scaffold', () => {
+    // ctx variant that records the ifAbsent flag passed to emitFile.
+    function makeScaffoldCtx(rootDir = '/project', options: Record<string, unknown> = {}): PluginContext & {
+        emitted: Map<string, { content: string; ifAbsent?: boolean }>;
+    } {
+        const emitted = new Map<string, { content: string; ifAbsent?: boolean }>();
+        return {
+            rootDir,
+            options,
+            cacheEnabled: true,
+            cacheDir: `${rootDir}/.contractkit/cache`,
+            emitFile: (outPath: string, content: string, opts?: { ifAbsent?: boolean }) => {
+                emitted.set(outPath, { content, ifAbsent: opts?.ifAbsent });
+            },
+            emitted,
+        };
+    }
+
+    function find(emitted: Map<string, { content: string; ifAbsent?: boolean }>, suffix: string) {
+        for (const [path, value] of emitted) if (path.endsWith(suffix)) return { path, ...value };
+        return undefined;
+    }
+
+    function eventInputs() {
+        // An op that responds with the Event model (has a datetime field) so the type
+        // is publicly reachable and surfaces into the SDK.
+        const root = opRoot(
+            [opRoute('/events', [opOperation('get', { sdk: 'getEvent', responses: [opResponse(200, 'Event', 'application/json')] })])],
+            '/project/contracts/events.ck',
+        );
+        return {
+            contractRoots: [contractRoot([model('Event', [field('id', scalarType('uuid')), field('at', scalarType('datetime'))])], '/project/contracts/events.ck')],
+            opRoots: [root],
+            modelOutPaths: new Map<string, string>(),
+            modelsWithInput: new Set<string>(),
+            modelsWithOutput: new Set<string>(),
+        };
+    }
+
+    it('does not emit scaffold files unless scaffold is enabled', async () => {
+        const plugin = createTypescriptPlugin(
+            { sdk: { baseDir: 'packages/sdk', output: { sdk: 'src/sdk.ts', clients: 'src/{filename}.client.ts', types: 'src/types/{filename}.ts' } } },
+            '/project',
+        );
+        const ctx = makeScaffoldCtx();
+        await plugin.generateTargets!(eventInputs(), ctx);
+        expect(find(ctx.emitted, 'package.json')).toBeUndefined();
+        expect(find(ctx.emitted, 'tsconfig.json')).toBeUndefined();
+    });
+
+    it('emits package.json and tsconfig.json at the SDK baseDir as ifAbsent files', async () => {
+        const plugin = createTypescriptPlugin(
+            {
+                sdk: {
+                    baseDir: 'packages/sdk',
+                    name: 'my-sdk',
+                    zod: true,
+                    scaffold: true,
+                    output: { sdk: 'src/sdk.ts', clients: 'src/{filename}.client.ts', types: 'src/types/{filename}.ts' },
+                },
+            },
+            '/project',
+        );
+        const ctx = makeScaffoldCtx();
+        await plugin.generateTargets!(eventInputs(), ctx);
+
+        const pkg = find(ctx.emitted, 'packages/sdk/package.json');
+        const tsconfig = find(ctx.emitted, 'packages/sdk/tsconfig.json');
+        expect(pkg).toBeDefined();
+        expect(tsconfig).toBeDefined();
+        // Both are write-once scaffold files.
+        expect(pkg!.ifAbsent).toBe(true);
+        expect(tsconfig!.ifAbsent).toBe(true);
+        // Name carried from sdk.name; zod (enabled) and luxon (datetime field) detected.
+        const parsed = JSON.parse(pkg!.content);
+        expect(parsed.name).toBe('my-sdk');
+        expect(parsed.dependencies.zod).toBeDefined();
+        expect(parsed.dependencies.luxon).toBeDefined();
+    });
+
+    it('omits luxon when no covered model uses a date/time scalar', async () => {
+        const root = opRoot(
+            [opRoute('/things', [opOperation('get', { sdk: 'getThing', responses: [opResponse(200, 'Thing', 'application/json')] })])],
+            '/project/contracts/things.ck',
+        );
+        const plugin = createTypescriptPlugin(
+            { sdk: { baseDir: 'packages/sdk', scaffold: true, output: { sdk: 'src/sdk.ts', clients: 'src/{filename}.client.ts', types: 'src/types/{filename}.ts' } } },
+            '/project',
+        );
+        const ctx = makeScaffoldCtx();
+        await plugin.generateTargets!(
+            {
+                contractRoots: [contractRoot([model('Thing', [field('id', scalarType('uuid'))])], '/project/contracts/things.ck')],
+                opRoots: [root],
+                modelOutPaths: new Map<string, string>(),
+                modelsWithInput: new Set<string>(),
+                modelsWithOutput: new Set<string>(),
+            },
+            ctx,
+        );
+        const pkg = JSON.parse(find(ctx.emitted, 'packages/sdk/package.json')!.content);
+        expect(pkg.dependencies?.luxon).toBeUndefined();
+        // zod also absent (zod not enabled) → no dependencies block at all.
+        expect(pkg.dependencies).toBeUndefined();
+    });
+});