ignotum 0.0.13 → 0.0.15

package/src/cli/new-app.ts

@@ -2,7 +2,7 @@ import { Effect, FileSystem, Path, Schema, String } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 
 import { agentAppFiles, type AppFile } from "./agent-files.js";
-import { generate } from "./codegen.js";
+import { generateClientRoutes } from "./route-codegen.js";
 import { installDependencies, type PackageManager } from "./package-manager.js";
 
 export interface NewAppOptions {
@@ -135,43 +135,6 @@ export const increment = mutation({
 });
 `;
 
-const app = `import { app, Result, useMutation, useQuery } from "ignotum/client";
-
-import { api } from "@/_generated/api.js";
-import { counterIncrement } from "@/shared/utils.js";
-
-function App() {
-  const count = useQuery(api.counter.get);
-  const increment = useMutation(api.counter.increment);
-
-  return (
-    <main class="mx-auto max-w-sm px-6 py-20 text-center">
-      <h1 class="text-2xl font-semibold">Counter</h1>
-      {Result.match(count, {
-        pending: () => <p class="mt-6">Loading...</p>,
-        value: (value) => (
-          <>
-            <p class="my-6 text-5xl tabular-nums">{value}</p>
-            <button
-              class="rounded bg-zinc-900 px-4 py-2 text-white"
-              type="button"
-              onClick={() => void increment()}
-            >
-              Increment by {counterIncrement}
-            </button>
-          </>
-        ),
-      })}
-    </main>
-  );
-}
-
-export default app({
-  title: "Counter",
-  component: App,
-});
-`;
-
 const icon = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
   <rect width="64" height="64" rx="14" fill="#18181b" />
   <path d="M20 32h24M32 20v24" stroke="#fafafa" stroke-width="6" stroke-linecap="round" />
@@ -181,73 +144,134 @@ const icon = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
 const utils = `export const counterIncrement = 1;
 `;
 
-const readme = (appName: string): string => `# ${appName}
-
-A small Ignotum counter app.
-
-## Getting started
-
-You need Node.js 22.18 or newer. The app generator installs dependencies by default. If you
-created the app with \`--no-install\`, install them now:
+const home = `import { Result, useMutation, useQuery } from "ignotum/client";
+import { api } from "@/_generated/api.js";
+import { route } from "@/_generated/client.js";
+import { counterIncrement } from "@/shared/utils.js";
 
-\`\`\`sh
-npx ignotum install
-\`\`\`
+export default route({
+  title: "Counter",
+  component: function Counter() {
+    const count = useQuery(api.counter.get);
+    const increment = useMutation(api.counter.increment);
+
+    return (
+      <section class="text-center">
+        <h1 class="text-2xl font-semibold">Counter</h1>
+        {Result.match(count, {
+          pending: () => <p class="mt-6">Loading...</p>,
+          value: (value) => (
+            <>
+              <p class="my-6 text-5xl tabular-nums">{value}</p>
+              <button
+                class="rounded bg-zinc-900 px-4 py-2 text-white"
+                type="button"
+                onClick={() => void increment()}
+              >
+                Increment by {counterIncrement}
+              </button>
+            </>
+          ),
+        })}
+      </section>
+    );
+  },
+});
+`;
 
-This command uses pnpm when it is installed and otherwise uses npm.
+const rootLayout = `import { Link } from "ignotum/client";
+import { layout } from "@/_generated/client.js";
+import { routes } from "@/_generated/routes.js";
+import "./styles.css";
+
+export default layout({
+  meta: { description: "A live counter built with Ignotum." },
+  component: function RootLayout({ children }) {
+    return (
+      <div class="mx-auto max-w-sm px-6 py-12">
+        <nav aria-label="Main" class="mb-10 flex justify-center gap-6">
+          <Link to={routes.index}>Counter</Link>
+          <Link to={routes.about}>About</Link>
+        </nav>
+        <main>{children}</main>
+      </div>
+    );
+  },
+});
+`;
 
-Start the app:
+const about = `import { Link } from "ignotum/client";
+import { route } from "@/_generated/client.js";
+import { routes } from "@/_generated/routes.js";
+
+export default route({
+  title: "About",
+  component: function About() {
+    return (
+      <section>
+        <h1 class="text-2xl font-semibold">About this counter</h1>
+        <p class="my-6">Open the counter in two tabs to see live updates.</p>
+        <Link to={routes.index}>Back to the counter</Link>
+      </section>
+    );
+  },
+});
+`;
 
-\`\`\`sh
-npx ignotum dev
-\`\`\`
+const readme = (appName: string) => `# ${appName}
 
-Open <http://127.0.0.1:3210>.
+An Ignotum counter app with live updates and two pages.
 
-The app generator creates \`_generated\`. The dev server checks those files before it starts
-and updates them when the schema or server functions change.
+## App files
 
-## Deploy
+- \`client/index.tsx\` defines the home page with \`route(...)\`.
+- \`client/about.tsx\` defines the About page at \`/about\`.
+- \`client/+layout.tsx\` shares navigation and styles across pages. Put shared providers here.
+- \`client/styles.css\` contains app-wide styles. Ignotum supplies Tailwind CSS automatically.
+- \`client/icon.svg\` is the optional app icon.
+- \`server/schema.ts\` defines tables and \`server/counter.ts\` defines the counter functions.
+- \`shared/utils.ts\` contains code used by the client and server.
+- \`_generated\` contains generated bindings. Never edit these files.
 
-Sign in, then choose a unique slug on the first deployment:
+Import \`route\`, \`layout\`, and URL \`values\` from \`@/_generated/client.js\`.
+Import \`routes\` from \`@/_generated/routes.js\` and pass a reference to \`Link\`:
 
-\`\`\`sh
-npx ignotum auth login
-npx ignotum deploy --app my-app
+\`\`\`tsx
+<Link to={routes.about}>About</Link>
 \`\`\`
 
-The command prints the hosted URL and records the app link in \`.ignotum/app.json\`. Later
-deployments use \`npx ignotum deploy\` without the \`--app\` flag.
-
-## App files
+Page filenames determine URLs. Put helpers and shared components in files or folders starting
+with \`_\` so they do not become pages. Keep the \`.js\` suffix on TypeScript imports.
 
-- \`server/schema.ts\` defines the database tables.
-- \`server/counter.ts\` defines the query and mutation used by the counter.
-- \`client/index.tsx\` defines the app title and UI.
-- \`client/icon.svg\` is the optional app icon.
-- Ignotum loads Tailwind CSS automatically. Custom CSS files are ordinary client modules.
-- \`shared/utils.ts\` contains code shared across the app.
-- \`_generated\` contains Ignotum's generated types and bindings. Do not edit it by hand.
-- \`.agents/skills/ignotum\` contains the app skill and references used by coding agents.
+## Development
 
-Run the typechecker after a change:
+Use Node.js 22.18 or newer. Install dependencies before starting development.
+Run \`npx ignotum install\` if dependencies are missing, then \`npx ignotum dev\`.
+Open <http://127.0.0.1:3210>. The development server generates server, client, and route bindings
+and updates them after edits. Run \`npx ignotum codegen\` to regenerate them separately.
+After generating bindings, run \`npx tsc --noEmit\` to check the app.
 
-\`\`\`sh
-npx ignotum codegen
-npx tsc --noEmit
-\`\`\`
+## Deploy
 
-The [Ignotum documentation](https://docs.ignotum.cloud) covers schema values, indexes, queries,
-mutations, client hooks, deployment, guarantees, and hosted limits.
+Sign in with \`npx ignotum auth login\`, then run \`npx ignotum deploy --app my-app\`.
+Later deployments use \`npx ignotum deploy\`. The command prints the hosted URL and confirms
+that the numbered App Version is live. If activation cannot be confirmed, follow the printed
+\`ignotum deploy --resume <version-id>\` command to finish without creating another version.
 
-## Claude Code
+## Coding agents
 
-If you use Claude Code, rename \`AGENTS.md\` to \`CLAUDE.md\` and \`.agents\` to \`.claude\` so it
-can find the app instructions and Ignotum skill.
+Read \`AGENTS.md\` and \`.agents/skills/ignotum/SKILL.md\` before editing.
+For Claude Code, rename \`AGENTS.md\` to \`CLAUDE.md\` and \`.agents\` to \`.claude\`.
 `;
 
-const appFiles = (appName: string): ReadonlyArray<AppFile> => [
-  { content: app, path: "client/index.tsx" },
+export const appFiles = (appName: string): ReadonlyArray<AppFile> => [
+  { content: home, path: "client/index.tsx" },
+  { content: rootLayout, path: "client/+layout.tsx" },
+  { content: about, path: "client/about.tsx" },
+  {
+    content: "body { margin: 0; background: #fafafa; color: #18181b; }\n",
+    path: "client/styles.css",
+  },
   { content: icon, path: "client/icon.svg" },
   { content: counterFunctions, path: "server/counter.ts" },
   { content: schema, path: "server/schema.ts" },
@@ -376,7 +400,7 @@ export const createApp = Effect.fn("NewApp.createApp")(function* (options: NewAp
     discard: true,
   });
 
-  yield* generate(appDirectory);
+  yield* generateClientRoutes(appDirectory);
 
   const packageManager = options.install ? yield* installDependencies(appDirectory) : null;
 

package/src/cli/route-codegen.ts

@@ -0,0 +1,311 @@
+import { Effect, FileSystem, Path, Schema } from "effect";
+import { createServer } from "vite";
+import {
+  AppModuleId,
+  LayoutDefinition,
+  RouteDefinition,
+  type UrlField,
+} from "@ignotum/contracts/app-definition";
+import { compilePatterns, parsePattern } from "@ignotum/shared/routing/pattern";
+import {
+  generate,
+  generatedHeader,
+  generatedImageTypes,
+  inspectOutput,
+  writeOutput,
+} from "./codegen.js";
+import { createRouteExtractor, InvalidRouteSource, sourceError } from "./route-static.js";
+
+export interface DiscoveredClientModule {
+  readonly path: string;
+  readonly relativePath: string;
+  readonly id: AppModuleId;
+  readonly kind: "route" | "layout";
+  readonly referenceKeys: ReadonlyArray<string>;
+}
+export interface ClientRouteDiscovery {
+  readonly routes: ReadonlyArray<RouteDefinition>;
+  readonly layouts: ReadonlyArray<LayoutDefinition>;
+  readonly modules: ReadonlyArray<DiscoveredClientModule>;
+  readonly dependencies: ReadonlyArray<string>;
+}
+const byName = (a: string, b: string) => (a < b ? -1 : a > b ? 1 : 0);
+const contains = (directory: string, child: string) =>
+  directory === "/" || child === directory || child.startsWith(`${directory}/`);
+const toPattern = (parts: ReadonlyArray<string>) =>
+  `/${parts.map((part) => (part.startsWith("$$") ? `*${part.slice(2)}` : part.startsWith("$") ? `:${part.slice(1)}` : part)).join("/")}`;
+const diagnostic = (file: string, message: string) =>
+  sourceError({ path: file, source: "" }, { start: 0 }, "route", message);
+const candidate = (name: string) =>
+  /\.(ts|tsx)$/.test(name) && !/\.(test|spec|d)\.(ts|tsx)$/.test(name) && !name.startsWith("_");
+
+export const discoverClientRoutes = Effect.fn("Routes.discoverClientRoutes")(function* (
+  directory: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const appDirectory = yield* fs.realPath(directory);
+  const clientDirectory = path.join(appDirectory, "client");
+  const files: string[] = [];
+  const seen = new Set<string>();
+  const visit = Effect.fn("Routes.visitDirectory")(function* (
+    directory: string,
+  ): Effect.fn.Return<void, InvalidRouteSource> {
+    const real = yield* fs
+      .realPath(directory)
+      .pipe(Effect.mapError(() => diagnostic(directory, "Cannot read route directory.")));
+    if (real !== clientDirectory && !real.startsWith(`${clientDirectory}/`))
+      return yield* diagnostic(directory, "Route trees cannot escape client/ through symlinks.");
+    if (seen.has(real)) return yield* diagnostic(directory, "Repeated or cyclic route directory.");
+    seen.add(real);
+    const entries = yield* fs
+      .readDirectory(directory)
+      .pipe(Effect.mapError(() => diagnostic(directory, "Cannot read route directory.")));
+    for (const name of entries.sort(byName)) {
+      if (name.startsWith("_") || name.startsWith(".")) continue;
+      const file = path.join(directory, name);
+      const info = yield* fs
+        .stat(file)
+        .pipe(Effect.mapError(() => diagnostic(file, "Cannot inspect route source.")));
+      if (info.type === "Directory") yield* visit(file);
+      else if (info.type === "File" && candidate(name)) files.push(file);
+    }
+  });
+  yield* visit(clientDirectory);
+  if (
+    !files.some(
+      (file) =>
+        path.dirname(file) === clientDirectory && /^index\.(ts|tsx)$/.test(path.basename(file)),
+    )
+  )
+    return yield* diagnostic(
+      clientDirectory,
+      "A client/index.ts or client/index.tsx home page is required.",
+    );
+  return yield* Effect.scoped(
+    Effect.gen(function* () {
+      // Resolve only. No transforms, SSR runner, user Vite config, or app module evaluation.
+      const server = yield* Effect.acquireRelease(
+        Effect.tryPromise({
+          try: () =>
+            createServer({
+              root: appDirectory,
+              configFile: false,
+              envFile: false,
+              appType: "custom",
+              logLevel: "silent",
+              css: { postcss: {} },
+              optimizeDeps: { noDiscovery: true },
+              resolve: { tsconfigPaths: true },
+              server: { middlewareMode: true, watch: null, hmr: false },
+            }),
+          catch: () => diagnostic(clientDirectory, "Cannot initialize the app import resolver."),
+        }),
+        (server) => Effect.promise(() => server.close()),
+      );
+      const extractor = yield* createRouteExtractor(appDirectory, (specifier, importer) =>
+        Effect.tryPromise({
+          try: async () => {
+            const resolved = await server.environments.client.pluginContainer.resolveId(
+              specifier,
+              importer,
+            );
+            if (
+              resolved === null ||
+              (resolved.external !== undefined && resolved.external !== false) ||
+              resolved.id.includes("?")
+            )
+              throw new Error("Unresolved app module");
+            return resolved.id;
+          },
+          catch: () =>
+            diagnostic(importer, `Cannot resolve '${specifier}' as an app source module.`),
+        }),
+      );
+      const modules: DiscoveredClientModule[] = [];
+      const layouts: LayoutDefinition[] = [];
+      const pending: {
+        readonly file: string;
+        readonly scope: string;
+        readonly pattern: string;
+        readonly extracted: Effect.Success<ReturnType<typeof extractor.extract>>;
+        readonly module: DiscoveredClientModule;
+      }[] = [];
+      for (const file of files.sort(byName)) {
+        const relativePath = path.relative(clientDirectory, file).split(path.sep).join("/");
+        const keys = relativePath.replace(/\.(ts|tsx)$/, "").split("/");
+        const kind = keys.at(-1) === "+layout" ? "layout" : "route";
+        if (keys.some((key) => key.startsWith("+") && key !== "+layout"))
+          return yield* diagnostic(file, "Unsupported reserved route file name.");
+        const scope = toPattern(keys.slice(0, -1));
+        const pattern = toPattern(
+          keys.at(-1) === "index" || kind === "layout" ? keys.slice(0, -1) : keys,
+        );
+        const parsed = yield* parsePattern(pattern).pipe(
+          Effect.mapError((error) => diagnostic(file, error.message)),
+        );
+        // Source names can contain $, +, Unicode, and punctuation. Module identities use a reversible hex encoding.
+        const id = yield* Schema.decodeUnknownEffect(AppModuleId)(
+          `app/client/m${Buffer.from(relativePath).toString("hex")}.js`,
+        ).pipe(
+          Effect.mapError(() =>
+            diagnostic(file, "Route source name exceeds module identity limits."),
+          ),
+        );
+        const module = {
+          path: file,
+          relativePath,
+          id,
+          kind,
+          referenceKeys: kind === "route" ? keys : [],
+        } satisfies DiscoveredClientModule;
+        modules.push(module);
+        const extracted = yield* extractor.extract(file, kind);
+        if (kind === "layout") {
+          const layout = yield* Schema.decodeUnknownEffect(LayoutDefinition)({
+            id: `layout:${relativePath}`,
+            scope: parsed.pattern,
+            module: { module: id, exportName: "default" },
+            metadata: extracted.metadata,
+            boundaries: extracted.boundaries,
+          }).pipe(Effect.mapError((error) => diagnostic(file, String(error))));
+          layouts.push(layout);
+        } else pending.push({ file, scope, pattern, extracted, module });
+      }
+      const nestedLayouts = layouts.map((layout) => {
+        const parent = layouts
+          .filter((other) => other.id !== layout.id && contains(other.scope, layout.scope))
+          .sort((a, b) => b.scope.length - a.scope.length)[0]?.id;
+        // An explicit undefined encodes as null and changes the persisted definition identity.
+        return parent === undefined ? layout : { ...layout, parent };
+      });
+      const routes: RouteDefinition[] = [];
+      for (const { file, scope, pattern, extracted, module } of pending) {
+        const parsed = yield* parsePattern(pattern);
+        const params: ReadonlyArray<UrlField> =
+          extracted.params ??
+          parsed.segments.flatMap((segment) =>
+            segment.kind === "Literal"
+              ? []
+              : [
+                  {
+                    name: segment.name,
+                    value:
+                      segment.kind === "Parameter"
+                        ? { type: "string" as const }
+                        : { type: "array" as const, value: { type: "string" as const } },
+                  },
+                ],
+          );
+        const route = yield* Schema.decodeUnknownEffect(RouteDefinition)({
+          id: `route:${module.relativePath}`,
+          pattern,
+          directoryScope: scope,
+          precedence: parsed.precedence,
+          params,
+          searchParams: extracted.searchParams,
+          page: { module: module.id, exportName: "default" },
+          layouts: nestedLayouts
+            .filter((layout) => contains(layout.scope, scope))
+            .sort((a, b) => a.scope.length - b.scope.length)
+            .map((layout) => layout.id),
+          metadata: extracted.metadata,
+          boundaries: { error: extracted.boundaries.error, invalid: extracted.boundaries.invalid },
+        }).pipe(Effect.mapError((error) => diagnostic(file, String(error))));
+        routes.push(route);
+      }
+      yield* compilePatterns(routes, nestedLayouts).pipe(
+        Effect.mapError((error) => diagnostic(clientDirectory, error.message)),
+      );
+      return {
+        routes,
+        layouts: nestedLayouts,
+        modules,
+        dependencies: [...extractor.dependencies].sort(byName),
+      } satisfies ClientRouteDiscovery;
+    }),
+  );
+});
+
+export const renderClientBindings = (): string => `${generatedHeader}
+
+${generatedImageTypes}
+
+import { bindSchema } from "ignotum/internal/client";
+import type { DataModel } from "./types.js";
+
+export const { route, layout, values } = bindSchema<DataModel>();
+`;
+interface ReferenceTree {
+  reference?: string;
+  readonly children: Map<string, ReferenceTree>;
+}
+export const renderRouteReferences = (discovery: ClientRouteDiscovery): string => {
+  const tree: ReferenceTree = { children: new Map() };
+  const references: string[] = [];
+  for (const [index, route] of discovery.routes.entries()) {
+    const module = discovery.modules.find((module) => module.id === route.page.module)!;
+    const name = `route${index}`;
+    const params = route.params
+      .map(
+        (field) =>
+          `${JSON.stringify(field.name)}: ${field.value.type === "array" ? "readonly string[]" : "string"}`,
+      )
+      .join("; ");
+    references.push(
+      `const ${name} = createRouteReference<typeof import(${JSON.stringify(`../client/${module.relativePath.replace(/\.(ts|tsx)$/, ".js")}`)}).default, { ${params} }>(${JSON.stringify(route, null, 2)});`,
+    );
+    let cursor = tree;
+    for (const key of module.referenceKeys) {
+      let child = cursor.children.get(key);
+      if (child === undefined) {
+        child = { children: new Map() };
+        cursor.children.set(key, child);
+      }
+      cursor = child;
+    }
+    cursor.reference = name;
+  }
+  const render = (node: ReferenceTree): string => {
+    const object = `{ ${[...node.children].map(([key, child]) => `[${JSON.stringify(key)}]: ${render(child)}`).join(", ")} }`;
+    return node.reference === undefined
+      ? object
+      : node.children.size === 0
+        ? node.reference
+        : `Object.assign(${node.reference}, ${object})`;
+  };
+  return `${generatedHeader}\n\nimport { createRouteReference } from "ignotum/internal/client";\n\n${references.join("\n\n")}\n\nexport const routes = ${render(tree)};\n`;
+};
+
+export const generateClientRoutes = Effect.fn("Routes.generateClientRoutes")(function* (
+  appDirectory: string,
+) {
+  const path = yield* Path.Path;
+  const server = yield* generate(appDirectory);
+  const client = {
+    path: path.join(appDirectory, "_generated/client.ts"),
+    content: renderClientBindings(),
+  };
+  const clientInspection = yield* inspectOutput(client);
+  if (clientInspection === "write") yield* writeOutput(client);
+  const discovery = yield* discoverClientRoutes(appDirectory);
+  const routes = {
+    path: path.join(appDirectory, "_generated/routes.ts"),
+    content: renderRouteReferences(discovery),
+  };
+  const routesInspection = yield* inspectOutput(routes);
+  if (routesInspection === "write") yield* writeOutput(routes);
+  return {
+    ...discovery,
+    written: [
+      ...server.written,
+      ...(clientInspection === "write" ? [client.path] : []),
+      ...(routesInspection === "write" ? [routes.path] : []),
+    ],
+    unchanged: [
+      ...server.unchanged,
+      ...(clientInspection === "unchanged" ? [client.path] : []),
+      ...(routesInspection === "unchanged" ? [routes.path] : []),
+    ],
+  };
+});