instant-cli 1.0.39 → 1.0.40-branch-python-sdk-v1.26482536960.1

package/src/commands/genpy.ts

@@ -0,0 +1,472 @@
+import { FileSystem, Path } from '@effect/platform';
+import chalk from 'chalk';
+import { Effect, Schema } from 'effect';
+import { readLocalSchemaFile } from '../old.js';
+import {
+  ReadSchemaFileError,
+  SchemaValidationError,
+} from '../lib/pushSchema.ts';
+
+export class GenpyWriteError extends Schema.TaggedError<GenpyWriteError>(
+  'GenpyWriteError',
+)('GenpyWriteError', {
+  message: Schema.String,
+}) {}
+
+const PY_HEADER = `# AUTOGENERATED by \`instant-cli genpy\`. DO NOT EDIT THIS FILE BY HAND.
+# Re-run \`npx instant-cli genpy\` after schema changes.
+`;
+
+export const genpyCommand = ({ outDir }: { outDir?: string }) =>
+  Effect.gen(function* () {
+    const localSchemaFile = yield* Effect.tryPromise({
+      try: readLocalSchemaFile,
+      catch: (e) =>
+        e instanceof Error
+          ? ReadSchemaFileError.make({ message: e.message })
+          : ReadSchemaFileError.make({ message: String(e) }),
+    });
+    if (!localSchemaFile || !localSchemaFile.schema) {
+      return yield* ReadSchemaFileError.make({
+        message: `We couldn't find your ${chalk.yellow('`instant.schema.ts`')} file. Make sure it's in the project root or under \`src/\`. (Hint: set INSTANT_SCHEMA_FILE_PATH to override.)`,
+      });
+    }
+    if (localSchemaFile.schema.constructor?.name !== 'InstantSchemaDef') {
+      return yield* SchemaValidationError.make({
+        message: `We couldn't find your schema export.\nIn your ${chalk.yellow('`instant.schema.ts`')} file, make sure you ${chalk.green('`export default schema`')}`,
+      });
+    }
+
+    const path = yield* Path.Path;
+    const fs = yield* FileSystem.FileSystem;
+    // Default: write alongside the schema file. `--out-dir` overrides for
+    // monorepos where Python lives elsewhere, or for our own sandbox where
+    // the schema is shared with the JS CLI tests.
+    const targetDir = outDir ? path.resolve(outDir) : path.dirname(localSchemaFile.path);
+    yield* fs.makeDirectory(targetDir, { recursive: true }).pipe(
+      Effect.mapError((e) =>
+        GenpyWriteError.make({ message: `Failed to create ${targetDir}: ${e}` }),
+      ),
+    );
+    const pyPath = path.join(targetDir, 'instant_types.py');
+    const pyiPath = path.join(targetDir, 'instant_types.pyi');
+
+    const pyContent = buildEntityModelsPy(localSchemaFile.schema);
+    const pyiContent = buildTxStubPyi(localSchemaFile.schema);
+    yield* fs.writeFileString(pyPath, pyContent).pipe(
+      Effect.mapError((e) =>
+        GenpyWriteError.make({ message: `Failed to write ${pyPath}: ${e}` }),
+      ),
+    );
+    yield* fs.writeFileString(pyiPath, pyiContent).pipe(
+      Effect.mapError((e) =>
+        GenpyWriteError.make({ message: `Failed to write ${pyiPath}: ${e}` }),
+      ),
+    );
+
+    yield* Effect.log(`✅ Wrote ${pyPath} and ${pyiPath}`);
+  });
+
+// ---------- entity model codegen ----------
+
+type SchemaLike = {
+  entities: Record<string, EntityDefLike>;
+  links: Record<string, LinkDefLike>;
+};
+
+type EntityDefLike = {
+  attrs: Record<string, DataAttrDefLike>;
+};
+
+type DataAttrDefLike = {
+  valueType: 'string' | 'number' | 'boolean' | 'date' | 'json';
+  required: boolean;
+};
+
+type LinkDefLike = {
+  forward: { on: string; label: string; has: 'one' | 'many' };
+  reverse: { on: string; label: string; has: 'one' | 'many' };
+};
+
+type Field = { name: string; type: string; hasDefault: boolean };
+
+function className(entName: string): string {
+  // Strip a leading `$` (system entities like `$users`, `$files`), then
+  // PascalCase across word separators (`-`, `_`, whitespace) so non-identifier
+  // characters in entity names don't produce invalid Python class names.
+  const stripped = entName.startsWith('$') ? entName.slice(1) : entName;
+  return stripped
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+}
+
+function mapValueType(vt: DataAttrDefLike['valueType']): string {
+  switch (vt) {
+    case 'string':
+      return 'str';
+    case 'number':
+      return 'float';
+    case 'boolean':
+      return 'bool';
+    case 'date':
+      return 'datetime';
+    case 'json':
+      return 'Any';
+    default:
+      // Defensive: if a new valueType ever lands in the schema without a
+      // genpy update, fall back to Any so generated code stays valid Python.
+      return 'Any';
+  }
+}
+
+export function buildEntityModelsPy(schema: SchemaLike): string {
+  const entityNames = Object.keys(schema.entities).sort();
+  const fieldsByEntity: Record<string, Field[]> = {};
+  const linkFieldsByEntity: Record<string, Field[]> = {};
+  let usesDatetime = false;
+
+  for (const entName of entityNames) {
+    fieldsByEntity[entName] = [{ name: 'id', type: 'str', hasDefault: false }];
+    linkFieldsByEntity[entName] = [];
+    for (const [attrName, attrDef] of Object.entries(
+      schema.entities[entName].attrs,
+    )) {
+      const baseType = mapValueType(attrDef.valueType);
+      if (baseType === 'datetime') usesDatetime = true;
+      const type = attrDef.required ? baseType : `${baseType} | None`;
+      fieldsByEntity[entName].push({
+        name: attrName,
+        type,
+        hasDefault: !attrDef.required,
+      });
+    }
+  }
+
+  for (const link of Object.values(schema.links)) {
+    const fwd = link.forward;
+    const rev = link.reverse;
+    if (linkFieldsByEntity[fwd.on]) {
+      linkFieldsByEntity[fwd.on].push({
+        name: fwd.label,
+        type:
+          fwd.has === 'one'
+            ? `${className(rev.on)} | None`
+            : `list[${className(rev.on)}] | None`,
+        hasDefault: true,
+      });
+    }
+    if (linkFieldsByEntity[rev.on]) {
+      linkFieldsByEntity[rev.on].push({
+        name: rev.label,
+        type:
+          rev.has === 'one'
+            ? `${className(fwd.on)} | None`
+            : `list[${className(fwd.on)}] | None`,
+        hasDefault: true,
+      });
+    }
+  }
+
+  // Sort link fields alphabetically for stable output across schema rewrites.
+  for (const entName of entityNames) {
+    linkFieldsByEntity[entName].sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  const classBlocks = entityNames.map((entName) => {
+    const lines = [
+      `class ${className(entName)}(BaseModel):`,
+      `    model_config = ConfigDict(extra="ignore")`,
+    ];
+    for (const f of [
+      ...fieldsByEntity[entName],
+      ...linkFieldsByEntity[entName],
+    ]) {
+      const decl = f.hasDefault
+        ? `    ${f.name}: ${f.type} = None`
+        : `    ${f.name}: ${f.type}`;
+      lines.push(decl);
+    }
+    return lines.join('\n');
+  });
+
+  const rebuilds = entityNames.map(
+    (entName) => `${className(entName)}.model_rebuild()`,
+  );
+
+  // Webhook record / handler types live in the same .py so users get one
+  // import point (`from instant_types import ...`) for both query results
+  // and webhook handler type-checking.
+  const webhookSection = buildWebhookSection(schema, entityNames);
+
+  const typingImports = ['Any', 'Callable', 'Literal', 'TypedDict'];
+
+  const stdlibImports: string[] = [];
+  if (usesDatetime) stdlibImports.push('from datetime import datetime');
+  stdlibImports.push(`from typing import ${typingImports.join(', ')}`);
+  const importBlock =
+    stdlibImports.join('\n') + '\n\n' +
+    'from pydantic import BaseModel, ConfigDict';
+
+  // Add record-model rebuilds so forward-string annotations to entity
+  // types resolve under `from __future__ import annotations`.
+  const recordRebuilds: string[] = [];
+  for (const entName of entityNames) {
+    const cls = className(entName);
+    for (const action of ['Create', 'Update', 'Delete']) {
+      recordRebuilds.push(`${cls}${action}Record.model_rebuild()`);
+    }
+  }
+
+  // Registry consumed by `Instant(schema=schema)`.
+  const entityMapLines = ['    "entities": {'];
+  for (const entName of entityNames) {
+    entityMapLines.push(`        ${JSON.stringify(entName)}: ${className(entName)},`);
+  }
+  entityMapLines.push('    },');
+  const recordMapLines = ['    "records": {'];
+  for (const entName of entityNames) {
+    const cls = className(entName);
+    for (const action of ['create', 'update', 'delete']) {
+      const capAction = action.charAt(0).toUpperCase() + action.slice(1);
+      recordMapLines.push(
+        `        (${JSON.stringify(entName)}, ${JSON.stringify(action)}): ${cls}${capAction}Record,`,
+      );
+    }
+  }
+  recordMapLines.push('    },');
+  const schemaLiteral = [
+    'schema = {',
+    ...entityMapLines,
+    ...recordMapLines,
+    '}',
+  ].join('\n');
+
+  return [
+    PY_HEADER + '"""Generated Pydantic models for Instant schema."""',
+    '',
+    'from __future__ import annotations',
+    '',
+    importBlock,
+    '',
+    '',
+    classBlocks.join('\n\n\n'),
+    '',
+    '',
+    '# Resolve forward references introduced by `from __future__ import annotations`.',
+    rebuilds.join('\n'),
+    '',
+    '',
+    webhookSection,
+    '',
+    '',
+    '# Rebuild webhook records so `before` / `after` annotations resolve to entity classes.',
+    recordRebuilds.join('\n'),
+    '',
+    '',
+    '# Registry consumed by `Instant(schema=schema)` for query-result + webhook validation.',
+    schemaLiteral,
+    '',
+  ].join('\n');
+}
+
+// ---------- webhook record / handler codegen ----------
+
+function buildWebhookSection(
+  schema: SchemaLike,
+  entityNames: string[],
+): string {
+  // Schemas with zero entities would produce `WebhookRecord = ` (no RHS).
+  if (entityNames.length === 0) return '';
+
+  const recordClasses: string[] = [];
+  const namespaceUnions: string[] = [];
+  const namespaceHandlerDicts: string[] = [];
+
+  // `before`/`after` shape varies by action.
+  const RECORD_VARIANTS = [
+    { action: 'create', before: 'None = None', afterTpl: (c: string) => c },
+    { action: 'update', before: 'CLS', afterTpl: (c: string) => c },
+    { action: 'delete', before: 'CLS', afterTpl: () => 'None = None' },
+  ] as const;
+
+  for (const entName of entityNames) {
+    const cls = className(entName);
+    for (const { action, before, afterTpl } of RECORD_VARIANTS) {
+      const cap = action.charAt(0).toUpperCase() + action.slice(1);
+      recordClasses.push(
+        [
+          `class ${cls}${cap}Record(BaseModel):`,
+          `    model_config = ConfigDict(extra="ignore")`,
+          `    namespace: Literal[${JSON.stringify(entName)}] = ${JSON.stringify(entName)}`,
+          `    id: str`,
+          `    action: Literal[${JSON.stringify(action)}] = ${JSON.stringify(action)}`,
+          `    before: ${before === 'CLS' ? cls : before}`,
+          `    after: ${afterTpl(cls)}`,
+          `    idempotencyKey: str`,
+        ].join('\n'),
+      );
+    }
+
+    namespaceUnions.push(
+      `${cls}Record = ${cls}CreateRecord | ${cls}UpdateRecord | ${cls}DeleteRecord`,
+    );
+
+    // Per-namespace handler TypedDict. Functional syntax so the `$default`
+    // key is expressible.
+    namespaceHandlerDicts.push(
+      [
+        `_${cls}Handlers = TypedDict(`,
+        `    "_${cls}Handlers",`,
+        '    {',
+        `        "create": Callable[[${cls}CreateRecord], Any],`,
+        `        "update": Callable[[${cls}UpdateRecord], Any],`,
+        `        "delete": Callable[[${cls}DeleteRecord], Any],`,
+        `        "$default": Callable[[${cls}Record], Any],`,
+        '    },',
+        '    total=False,',
+        ')',
+      ].join('\n'),
+    );
+  }
+
+  const rootUnionTerms = entityNames.map((n) => `${className(n)}Record`);
+  const rootUnion = `WebhookRecord = ${rootUnionTerms.join(' | ')}`;
+
+  const handlerDictLines = ['WebhookHandlers = TypedDict(', '    "WebhookHandlers",', '    {'];
+  for (const entName of entityNames) {
+    handlerDictLines.push(`        ${JSON.stringify(entName)}: _${className(entName)}Handlers,`);
+  }
+  handlerDictLines.push(`        "$default": Callable[[WebhookRecord], Any],`);
+  handlerDictLines.push('    },', '    total=False,', ')');
+
+  return [
+    '# ---------- webhook record models ----------',
+    '',
+    recordClasses.join('\n\n\n'),
+    '',
+    '',
+    '# ---------- webhook handler types ----------',
+    '',
+    namespaceUnions.join('\n'),
+    '',
+    rootUnion,
+    '',
+    '',
+    namespaceHandlerDicts.join('\n\n\n'),
+    '',
+    '',
+    handlerDictLines.join('\n'),
+  ].join('\n');
+}
+
+// ---------- tx builder .pyi stub ----------
+
+export function buildTxStubPyi(schema: SchemaLike): string {
+  const entityNames = Object.keys(schema.entities).sort();
+  let usesDatetime = false;
+
+  // Per-entity link fields (label + arg type for link/unlink TypedDict).
+  const linkFieldsByEntity: Record<string, { label: string; type: string }[]> =
+    {};
+  for (const entName of entityNames) {
+    linkFieldsByEntity[entName] = [];
+  }
+  for (const link of Object.values(schema.links)) {
+    const fwdArgType = link.forward.has === 'one' ? 'str' : 'str | list[str]';
+    const revArgType = link.reverse.has === 'one' ? 'str' : 'str | list[str]';
+    if (linkFieldsByEntity[link.forward.on]) {
+      linkFieldsByEntity[link.forward.on].push({
+        label: link.forward.label,
+        type: fwdArgType,
+      });
+    }
+    if (linkFieldsByEntity[link.reverse.on]) {
+      linkFieldsByEntity[link.reverse.on].push({
+        label: link.reverse.label,
+        type: revArgType,
+      });
+    }
+  }
+  for (const entName of entityNames) {
+    linkFieldsByEntity[entName].sort((a, b) => a.label.localeCompare(b.label));
+  }
+
+  const perEntityBlocks: string[] = [];
+  for (const entName of entityNames) {
+    const cls = className(entName);
+
+    const argsLines = [`class ${cls}Args(TypedDict, total=False):`];
+    for (const [attrName, attrDef] of Object.entries(
+      schema.entities[entName].attrs,
+    )) {
+      const t = mapValueType(attrDef.valueType);
+      if (t === 'datetime') usesDatetime = true;
+      argsLines.push(`    ${attrName}: ${t}`);
+    }
+    if (argsLines.length === 1) argsLines.push('    pass');
+    perEntityBlocks.push(argsLines.join('\n'));
+
+    const linkLines = [`class ${cls}Links(TypedDict, total=False):`];
+    for (const link of linkFieldsByEntity[entName]) {
+      linkLines.push(`    ${link.label}: ${link.type}`);
+    }
+    if (linkLines.length === 1) linkLines.push('    pass');
+    perEntityBlocks.push(linkLines.join('\n'));
+
+    perEntityBlocks.push(
+      [
+        `class _${cls}Chunk:`,
+        `    def update(self, args: ${cls}Args) -> _${cls}Chunk: ...`,
+        `    def create(self, args: ${cls}Args) -> _${cls}Chunk: ...`,
+        `    def link(self, args: ${cls}Links) -> _${cls}Chunk: ...`,
+        `    def unlink(self, args: ${cls}Links) -> _${cls}Chunk: ...`,
+        `    def delete(self) -> _${cls}Chunk: ...`,
+        `    def merge(self, args: ${cls}Args) -> _${cls}Chunk: ...`,
+      ].join('\n'),
+    );
+  }
+
+  const builderBlock = [
+    'class _NamespaceBuilder(Generic[ChunkT]):',
+    '    def __getitem__(self, eid: str) -> ChunkT: ...',
+    '    def lookup(self, attr: str, value: Any) -> ChunkT: ...',
+  ].join('\n');
+
+  // `$`-prefixed entities can't be reached via attribute syntax, so omit
+  // them from `_TxBuilder` attrs. Subscript form (`db.tx["$users"]`) still works.
+  const identifierEntities = entityNames.filter((n) => !n.startsWith('$'));
+  const txLines = ['class _TxBuilder:'];
+  if (identifierEntities.length === 0) {
+    txLines.push('    pass');
+  } else {
+    for (const entName of identifierEntities) {
+      txLines.push(`    ${entName}: _NamespaceBuilder[_${className(entName)}Chunk]`);
+    }
+  }
+
+  const stdlibImports = ['from typing import Any, Generic, TypedDict, TypeVar'];
+  if (usesDatetime) stdlibImports.unshift('from datetime import datetime');
+
+  return [
+    PY_HEADER + '"""Tx builder typing stub. Applied via `Instant(schema=...)`."""',
+    '',
+    'from __future__ import annotations',
+    '',
+    stdlibImports.join('\n'),
+    '',
+    '',
+    'ChunkT = TypeVar("ChunkT")',
+    '',
+    '',
+    perEntityBlocks.join('\n\n\n'),
+    '',
+    '',
+    builderBlock,
+    '',
+    '',
+    txLines.join('\n'),
+    '',
+  ].join('\n');
+}

package/src/index.ts

@@ -21,6 +21,7 @@ import { infoCommand } from './commands/info.ts';
 import { pullCommand } from './commands/pull.ts';
 import type { SchemaPermsOrBoth } from './commands/pull.ts';
 import { claimCommand } from './commands/claim.ts';
+import { genpyCommand } from './commands/genpy.ts';
 import { pushCommand } from './commands/push.ts';
 import { explorerCmd } from './commands/explorer.ts';
 import { queryCmd } from './commands/query.ts';
@@ -836,6 +837,28 @@ Environment Variables:
     );
   });
 
+export const genpyDef = program
+  .command('genpy')
+  .description(
+    'Generate Python types (instant_types.py + .pyi) from instant.schema.ts.',
+  )
+  .option(
+    '-o --out-dir <path>',
+    'Directory to write generated files into. Defaults to the schema file directory.',
+  )
+  .addHelpText(
+    'after',
+    `
+Environment Variables:
+  INSTANT_SCHEMA_FILE_PATH    Override schema file location (default: instant.schema.ts)
+`,
+  )
+  .action(async (opts) => {
+    return runCommandEffect(
+      genpyCommand({ outDir: opts.outDir }).pipe(Effect.provide(BaseLayerLive)),
+    );
+  });
+
 export const claimDef = program
   .command('claim')
   .description('Transfer a temporary app into your Instant account')