@relevate/katachi 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing
+
+Thanks for taking an interest in Katachi.
+
+## Before you start
+
+Katachi is still early. The current priority is keeping the compiler small, understandable, and honest about its supported surface.
+
+Please open an issue or discussion before starting large feature work, especially for:
+
+- new targets
+- new authoring syntax
+- parser rewrites
+- runtime behavior changes
+
+## Local setup
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm verify:examples
+```
+
+## Contribution guidelines
+
+- Keep changes focused.
+- Prefer extending the typed compiler model over adding special cases.
+- Add tests for parser, emitter, or build behavior when you change them.
+- Update docs when the supported authoring surface changes.
+- Do not broaden the supported TSX subset without documenting it.
+
+## Project shape
+
+The most important internal layers are:
+
+- `src/core/parser.ts`
+- `src/core/ast.ts`
+- `src/core/types.ts`
+- `src/targets/*`
+- `tests/*.test.ts`
+
+If you add a new target:
+
+1. create a target module in `src/targets/`
+2. register it in `src/targets/index.ts`
+3. add tests for the generated output
+
+## Scope
+
+Katachi is intentionally constrained.
+
+Non-goals include:
+
+- full React semantics
+- arbitrary JavaScript execution in templates
+- full Askama parity in the authoring language
+
+If a proposal pushes Katachi toward being a general-purpose framework compiler, it should be justified very carefully.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Relevate
+
+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

@@ -0,0 +1,194 @@
+# Katachi
+
+Katachi lets you author template-like components once in restricted TSX and
+compile them to multiple outputs.
+
+Today it can emit:
+
+- React TSX components
+- static-oriented TSX components
+- Askama Rust wrapper files
+- Askama include partials
+
+Katachi is still early, but it is already usable if you need one component
+source that can target both React-style environments and Askama.
+
+## Getting Started
+
+Try it once without installing it:
+
+```bash
+pnpm dlx @relevate/katachi build
+```
+
+or:
+
+```bash
+npx @relevate/katachi build
+```
+
+If you want Katachi in your project, install it:
+
+```bash
+pnpm add -D @relevate/katachi
+```
+
+or:
+
+```bash
+npm install --save-dev @relevate/katachi
+```
+
+Then add Katachi's JSX typing layer to `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "preserve",
+    "types": ["node", "@relevate/katachi/jsx"]
+  }
+}
+```
+
+If you already use a `types` array, append `@relevate/katachi/jsx` instead of
+replacing your existing entries.
+
+By default, Katachi reads templates from:
+
+```txt
+src/templates/**/*.template.tsx
+```
+
+Build from your project root:
+
+```bash
+pnpm exec katachi build
+```
+
+or without installing it first:
+
+```bash
+pnpm dlx @relevate/katachi build
+```
+
+By default, Katachi writes:
+
+- `dist/react`
+- `dist/jsx-static`
+- `dist/askama`
+- `dist/askama/includes`
+
+If you want custom paths:
+
+```bash
+pnpm exec katachi build --templates ./katachi/templates --dist ./generated
+```
+
+## First Template
+
+Start with a normal `.template.tsx` file:
+
+```tsx
+import { If, type TemplateNode } from "@relevate/katachi";
+
+export type Props = {
+  tone: "calm" | "urgent";
+  title: string;
+  children?: TemplateNode;
+};
+
+export default function NoticePanel({ tone, title, children }: Props) {
+  return (
+    <aside
+      className={[
+        "rounded-3xl border px-5 py-4",
+        tone == "calm" && "border-sky-200 bg-sky-50/80",
+        tone == "urgent" && "border-rose-200 bg-rose-50/80",
+      ]}
+    >
+      <h3>{title}</h3>
+      <If test={tone == "urgent"}>
+        <p>Action recommended</p>
+      </If>
+      {children}
+    </aside>
+  );
+}
+```
+
+Build it with:
+
+```bash
+pnpm exec katachi build
+```
+
+That generates target-specific files under `dist/`.
+
+## What Katachi Generates
+
+By default, build output goes to:
+
+- `dist/react/**/*.tsx`
+- `dist/jsx-static/**/*.tsx`
+- `dist/askama/**/*.rs`
+- `dist/askama/includes/**/*.html`
+
+Nested templates preserve their relative directory layout.
+
+## What Katachi Supports Today
+
+- template authoring in `src/templates/**/*.template.tsx`
+- imports between templates
+- dynamic `class` and `className` arrays
+- `If`
+- `For`
+- `safe(...)`
+- nested components
+- React output
+- static-oriented TSX output
+- Askama output
+
+## Why Katachi Exists
+
+At Relevate, our docs system is built in Rust and renders components with
+Askama. We also wanted a live editor that could use the same component
+structure and styling without maintaining a separate hand-written React
+component library.
+
+Katachi exists to make that possible: one authoring format, multiple outputs.
+
+## What Katachi Is Not
+
+- not a full React compiler
+- not a full Askama replacement
+- not arbitrary JavaScript execution in templates
+- not a general-purpose frontend framework
+
+## Documentation
+
+- [Getting started](./docs/getting-started.md)
+- [Template syntax](./docs/syntax.md)
+- [Target outputs](./docs/targets.md)
+- [Architecture](./docs/architecture.md)
+- [Consumer example](./examples/basic/README.md)
+
+## Current Limitations
+
+- The TSX input is not arbitrary React.
+- Generated React output is valid React, but the input syntax is compiler-owned.
+- The repository-level smoke tests build the public example project under `examples/basic`.
+
+## Contributing
+
+If you are working on Katachi itself rather than using it in another project:
+
+- `pnpm build`
+- `pnpm verify:examples`
+- `pnpm test`
+- `pnpm typecheck`
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) and [docs/architecture.md](./docs/architecture.md).
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/bin/katachi.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+const binDir = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(binDir, "..");
+const builtCliPath = resolve(packageRoot, "dist/cli/index.js");
+const sourceCliPath = resolve(packageRoot, "src/cli/index.ts");
+
+const hasBuiltCli = existsSync(builtCliPath);
+
+const result = spawnSync(
+  process.execPath,
+  hasBuiltCli
+    ? [builtCliPath, ...process.argv.slice(2)]
+    : ["--import", "tsx/esm", sourceCliPath, ...process.argv.slice(2)],
+  {
+    cwd: process.cwd(),
+    stdio: "inherit",
+  },
+);
+
+if (typeof result.status === "number") {
+  process.exit(result.status);
+}
+
+process.exit(1);

package/dist/api/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Public API helpers exposed to Katachi template files.
+ *
+ * These exports exist primarily for editor support and package consumers. The
+ * Katachi compiler parses template source text directly, so these helpers are
+ * not expected to execute in normal builds.
+ */
+export type ClassValue = string | number | boolean | null | undefined | ClassValue[];
+export type TemplateNode = string | number | boolean | null | undefined | TemplateNode[];
+export type IfProps = {
+    test: unknown;
+    children?: TemplateNode;
+};
+export type ForProps<T = unknown> = {
+    each: readonly T[] | T[] | null | undefined;
+    as: string;
+    index?: string;
+    children?: TemplateNode;
+};
+/**
+ * Placeholder runtime export for template files. The compiler reads source
+ * templates directly and never evaluates this function during normal use.
+ */
+export declare function If(_props: IfProps): TemplateNode;
+/**
+ * Placeholder runtime export for template files. The compiler reads source
+ * templates directly and never evaluates this function during normal use.
+ */
+export declare function For<T>(_props: ForProps<T>): TemplateNode;
+/**
+ * Marks a printed value as safe in Katachi templates. This is a no-op at the
+ * API layer because escaping is handled by target emitters.
+ */
+export declare function safe<T>(value: T): T;
+/**
+ * Portable length helper for Katachi templates.
+ */
+export declare function len(value: {
+    length: number;
+} | string | readonly unknown[] | null | undefined): number;
+/**
+ * Portable emptiness helper for Katachi templates.
+ */
+export declare function isEmpty(value: {
+    length: number;
+} | string | readonly unknown[] | null | undefined): boolean;
+/**
+ * Portable presence helper for Katachi templates.
+ */
+export declare function isSome<T>(value: T | null | undefined): value is T;
+/**
+ * Portable absence helper for Katachi templates.
+ */
+export declare function isNone<T>(value: T | null | undefined): value is null | undefined;

package/dist/api/index.js

@@ -0,0 +1,45 @@
+/**
+ * Placeholder runtime export for template files. The compiler reads source
+ * templates directly and never evaluates this function during normal use.
+ */
+export function If(_props) {
+    return null;
+}
+/**
+ * Placeholder runtime export for template files. The compiler reads source
+ * templates directly and never evaluates this function during normal use.
+ */
+export function For(_props) {
+    return null;
+}
+/**
+ * Marks a printed value as safe in Katachi templates. This is a no-op at the
+ * API layer because escaping is handled by target emitters.
+ */
+export function safe(value) {
+    return value;
+}
+/**
+ * Portable length helper for Katachi templates.
+ */
+export function len(value) {
+    return value?.length ?? 0;
+}
+/**
+ * Portable emptiness helper for Katachi templates.
+ */
+export function isEmpty(value) {
+    return (value?.length ?? 0) === 0;
+}
+/**
+ * Portable presence helper for Katachi templates.
+ */
+export function isSome(value) {
+    return value != null;
+}
+/**
+ * Portable absence helper for Katachi templates.
+ */
+export function isNone(value) {
+    return value == null;
+}

package/dist/api/jsx.d.ts

@@ -0,0 +1,26 @@
+import type { ClassValue, TemplateNode } from "./index.js";
+
+declare global {
+  namespace JSX {
+    /**
+     * Authoring templates do not produce real JSX runtime elements. The parser
+     * reads the source text and lowers it into Katachi AST nodes instead.
+     */
+    type Element = TemplateNode;
+
+    interface ElementChildrenAttribute {
+      children: {};
+    }
+
+    interface IntrinsicElements {
+      [elemName: string]: {
+        children?: TemplateNode;
+        class?: ClassValue;
+        className?: ClassValue;
+        [attrName: string]: unknown;
+      };
+    }
+  }
+}
+
+export {};

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/index.js

@@ -0,0 +1,77 @@
+import { resolve } from "node:path";
+import { buildProject } from "../core/build.js";
+import { verifyAskamaFixtures } from "../core/verify.js";
+import { basicExampleRoot, createExampleFixtures, exampleFixtures } from "../core/example-fixtures.js";
+function printHelp() {
+    console.log(`Katachi
+
+Usage:
+  katachi build [--project <dir>] [--templates <dir>] [--dist <dir>]
+  katachi verify:examples
+  katachi help
+
+Defaults:
+  --project   current working directory
+  --templates <project>/src/templates
+  --dist      <project>/dist`);
+}
+function parseArgs(argv) {
+    const [commandArg, ...rest] = argv;
+    const command = (commandArg ?? "build");
+    if (!["build", "verify:askama", "verify:examples", "help"].includes(command)) {
+        throw new Error(`Unknown command: ${command}`);
+    }
+    const options = { command };
+    for (let index = 0; index < rest.length; index += 1) {
+        const current = rest[index];
+        const next = rest[index + 1];
+        if (current === "--project" && next) {
+            options.projectRoot = resolve(next);
+            index += 1;
+            continue;
+        }
+        if (current === "--templates" && next) {
+            options.templatesDir = resolve(next);
+            index += 1;
+            continue;
+        }
+        if (current === "--dist" && next) {
+            options.distDir = resolve(next);
+            index += 1;
+            continue;
+        }
+        throw new Error(`Unknown or incomplete option: ${current}`);
+    }
+    return options;
+}
+function run() {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.command === "help") {
+        printHelp();
+        return;
+    }
+    if (options.command === "build") {
+        buildProject({
+            projectRoot: options.projectRoot,
+            templatesDir: options.templatesDir,
+            distDir: options.distDir,
+        });
+        return;
+    }
+    if (options.command === "verify:examples" || options.command === "verify:askama") {
+        const projectRoot = options.projectRoot ?? basicExampleRoot;
+        const distDir = options.distDir ?? resolve(projectRoot, "dist");
+        buildProject({
+            projectRoot,
+            templatesDir: options.templatesDir,
+            distDir,
+        });
+        verifyAskamaFixtures({
+            fixtures: projectRoot === basicExampleRoot && distDir === resolve(basicExampleRoot, "dist")
+                ? exampleFixtures
+                : createExampleFixtures(projectRoot, distDir),
+        });
+        return;
+    }
+}
+run();

package/dist/core/ast.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Canonical portable AST used by Katachi after parsing authoring input.
+ *
+ * Targets emit from this model instead of parsing templates themselves.
+ */
+export type Expr = {
+    kind: "var";
+    name: string;
+} | {
+    kind: "string";
+    value: string;
+} | {
+    kind: "bool";
+    value: boolean;
+} | {
+    kind: "number";
+    value: number;
+} | {
+    kind: "intrinsic";
+    name: "len" | "isEmpty" | "isSome" | "isNone";
+    args: Expr[];
+} | {
+    kind: "raw";
+    source: string;
+} | {
+    kind: "eq";
+    left: Expr;
+    right: Expr;
+} | {
+    kind: "neq";
+    left: Expr;
+    right: Expr;
+} | {
+    kind: "and";
+    left: Expr;
+    right: Expr;
+} | {
+    kind: "or";
+    left: Expr;
+    right: Expr;
+} | {
+    kind: "not";
+    expr: Expr;
+};
+export type ClassItem = {
+    kind: "static";
+    value: string;
+} | {
+    kind: "when";
+    test: Expr;
+    value: string;
+};
+export type AttrValue = {
+    kind: "text";
+    value: string;
+} | {
+    kind: "expr";
+    expr: Expr;
+} | {
+    kind: "classList";
+    items: ClassItem[];
+};
+export type Node = {
+    kind: "text";
+    value: string;
+} | {
+    kind: "slot";
+    name: string;
+} | {
+    kind: "print";
+    expr: Expr;
+    safe?: boolean;
+} | {
+    kind: "if";
+    test: Expr;
+    then: Node[];
+    else?: Node[];
+} | {
+    kind: "for";
+    item: string;
+    each: Expr;
+    children: Node[];
+    indexName?: string | null;
+} | {
+    kind: "element";
+    tag: string;
+    attrs?: Record<string, AttrValue>;
+    children?: Node[];
+} | {
+    kind: "component";
+    name: string;
+    props?: Record<string, AttrValue>;
+    children?: Node[];
+};
+export declare const v: (name: string) => Expr;
+export declare const s: (value: string) => Expr;
+export declare const b: (value: boolean) => Expr;
+export declare const n: (value: number) => Expr;
+export declare const intrinsic: (name: "len" | "isEmpty" | "isSome" | "isNone", ...args: Expr[]) => Expr;
+export declare const raw: (source: string) => Expr;
+export declare const eq: (left: Expr, right: Expr) => Expr;
+export declare const neq: (left: Expr, right: Expr) => Expr;
+export declare const and: (left: Expr, right: Expr) => Expr;
+export declare const or: (left: Expr, right: Expr) => Expr;
+export declare const not: (expr: Expr) => Expr;
+export declare const textAttr: (value: string) => AttrValue;
+export declare const exprAttr: (expr: Expr) => AttrValue;
+export declare const classList: (...items: ClassItem[]) => AttrValue;
+export declare const textNode: (value: string) => Node;
+export declare const slotNode: (name: string) => Node;
+export declare const printNode: (expr: Expr, safe?: boolean) => Node;
+export declare const ifNode: (test: Expr, thenNodes: Node[], elseNodes?: Node[]) => Node;
+export declare const forNode: (item: string, each: Expr, children?: Node[], indexName?: string | null) => Node;
+export declare const elementNode: (tag: string, attrs?: Record<string, AttrValue>, children?: Node[]) => Node;
+export declare const componentNode: (name: string, props?: Record<string, AttrValue>, children?: Node[]) => Node;

package/dist/core/ast.js

@@ -0,0 +1,51 @@
+/**
+ * Canonical portable AST used by Katachi after parsing authoring input.
+ *
+ * Targets emit from this model instead of parsing templates themselves.
+ */
+export const v = (name) => ({ kind: "var", name });
+export const s = (value) => ({ kind: "string", value });
+export const b = (value) => ({ kind: "bool", value });
+export const n = (value) => ({ kind: "number", value });
+export const intrinsic = (name, ...args) => ({
+    kind: "intrinsic",
+    name,
+    args,
+});
+export const raw = (source) => ({ kind: "raw", source });
+export const eq = (left, right) => ({ kind: "eq", left, right });
+export const neq = (left, right) => ({ kind: "neq", left, right });
+export const and = (left, right) => ({ kind: "and", left, right });
+export const or = (left, right) => ({ kind: "or", left, right });
+export const not = (expr) => ({ kind: "not", expr });
+export const textAttr = (value) => ({ kind: "text", value });
+export const exprAttr = (expr) => ({ kind: "expr", expr });
+export const classList = (...items) => ({ kind: "classList", items });
+export const textNode = (value) => ({ kind: "text", value });
+export const slotNode = (name) => ({ kind: "slot", name });
+export const printNode = (expr, safe = false) => ({ kind: "print", expr, safe });
+export const ifNode = (test, thenNodes, elseNodes = []) => ({
+    kind: "if",
+    test,
+    then: thenNodes,
+    else: elseNodes,
+});
+export const forNode = (item, each, children = [], indexName = null) => ({
+    kind: "for",
+    item,
+    each,
+    children,
+    indexName,
+});
+export const elementNode = (tag, attrs = {}, children = []) => ({
+    kind: "element",
+    tag,
+    attrs,
+    children,
+});
+export const componentNode = (name, props = {}, children = []) => ({
+    kind: "component",
+    name,
+    props,
+    children,
+});

package/dist/core/build.d.ts

@@ -0,0 +1,15 @@
+import type { BuildTemplate } from "./types.js";
+export interface BuildProjectOptions {
+    projectRoot?: string;
+    distDir?: string;
+    templatesDir?: string;
+    logger?: Pick<Console, "log">;
+}
+export interface BuildProjectResult {
+    templates: BuildTemplate[];
+    writtenFiles: string[];
+}
+/**
+ * Builds the current project and writes all configured outputs to `dist/`.
+ */
+export declare function buildProject(options?: BuildProjectOptions): BuildProjectResult;