@styx-api/core 0.1.0

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@styx-api/core",
+  "version": "0.1.0",
+  "description": "Styx compiler core: parses CLI tool descriptors (e.g. Boutiques), optimizes an IR, solves typed parameter bindings, and generates type-safe wrappers (TypeScript, Python, JSON Schema). Part of the Styx/NiWrap ecosystem.",
+  "keywords": [
+    "styx",
+    "niwrap",
+    "boutiques",
+    "code-generation",
+    "compiler",
+    "cli"
+  ],
+  "license": "MIT",
+  "homepage": "https://niwrap.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/styx-api/styx-ts.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/styx-api/styx-ts/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "development": "./src/index.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/test-helpers.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "prepublishOnly": "tsdown"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "rolldown": "1.0.0-rc.1",
+    "styxdefs": "^0.2.0",
+    "tsdown": "^0.20.1"
+  }
+}

package/src/backend/backend.ts

@@ -0,0 +1,95 @@
+import type { BoundType } from "../bindings/index.js";
+import type { AppMeta } from "../ir/index.js";
+import type { CodegenContext, PackageMeta, ProjectMeta } from "../manifest/index.js";
+import type { Scope } from "./scope.js";
+
+export interface EmitResult {
+  files: Map<string, string>;
+  errors: EmitError[];
+  warnings: EmitWarning[];
+}
+
+export interface EmitError {
+  message: string;
+}
+
+export interface EmitWarning {
+  message: string;
+}
+
+/**
+ * What the suite-level dispatcher needs to route a config object to one app's
+ * dict-style executor, keyed by the root `@type` discriminator.
+ */
+export interface AppEntrypoint {
+  /** Root `@type` discriminator value (`<package>/<app>`). */
+  type: string;
+  /**
+   * Dict-style execute function name - `<tool>Execute` / `<tool>_execute` for a
+   * struct root, `<tool>` for a non-struct root. Takes `(params, runner)`.
+   */
+  executeFn: string;
+}
+
+export interface EmittedApp extends EmitResult {
+  meta?: AppMeta;
+  /**
+   * Dispatch entrypoint, present when the app has a stable `@type` (both an id
+   * and a package name are known). Consumed by `emitPackage` to build the
+   * suite-level `execute(params, runner)` dispatcher.
+   */
+  entrypoint?: AppEntrypoint;
+}
+
+export interface EmittedPackage extends EmitResult {
+  meta?: PackageMeta;
+}
+
+/**
+ * A code generator for one target language. Implementations emit in up to
+ * three tiers; only `emitApp` is mandatory.
+ *
+ * The CLI's `--mode` flag selects which tiers run: `scripts` = `emitApp` only,
+ * `single` = `emitApp` + one `emitPackage`, `multi` = all three tiers.
+ *
+ * Paths in returned file maps are relative to the emit tier's natural root
+ * (package directory for app/package emit, project root for project emit).
+ * Orchestration is responsible for prefixing/merging the maps.
+ */
+export interface Backend {
+  readonly name: string;
+  readonly target: string;
+  /**
+   * Emit the per-tool file(s) for one app. Mandatory.
+   *
+   * When emitting many tools into one suite barrel, pass a `scope` shared across
+   * the package (from `newPackageScope`) so emitted top-level names stay unique
+   * across tools - a flat `export *` / `from .x import *` re-export otherwise
+   * collides same-named types. Omit it for standalone single-tool emission.
+   */
+  emitApp(ctx: CodegenContext, scope?: Scope): EmittedApp;
+  /**
+   * Create a fresh symbol scope seeded with this backend's reserved words, to be
+   * shared across all `emitApp` calls for one package. Optional; callers fall
+   * back to per-tool scoping (still safe via name prefixing) when absent.
+   */
+  newPackageScope?(): Scope;
+  /**
+   * Emit suite-level files for a package containing many apps (e.g. the
+   * `__init__.py` re-exporting `from .bet import *` per tool, or an
+   * `index.ts` doing `export * from "./bet.js"`). Optional; defaulted to
+   * no-op by callers when absent.
+   */
+  emitPackage?(pkg: PackageMeta, apps: EmittedApp[]): EmittedPackage;
+  /**
+   * Emit project-level artifacts spanning many packages (e.g. root
+   * `pyproject.toml`, top-level `__init__.py`, runner helpers).
+   * Wired up by Plan 2's CLI catalog mode; backends opt in as needed.
+   */
+  emitProject?(proj: ProjectMeta, packages: EmittedPackage[]): EmitResult;
+}
+
+export interface TypeMap {
+  map(type: BoundType): string;
+  imports(type: BoundType): string[];
+}