ignotum 0.0.2 → 0.0.4

package/src/cli/{new-project.ts → new-app.ts}

@@ -1,39 +1,36 @@
 import { Effect, FileSystem, Path, Schema, String } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 
-import { agentProjectFiles, type ProjectFile } from "./agent-files.js";
+import { agentAppFiles, type AppFile } from "./agent-files.js";
 import { generate } from "./codegen.js";
 import { installDependencies, type PackageManager } from "./package-manager.js";
 
-export interface NewProjectOptions {
+export interface NewAppOptions {
   readonly currentDirectory: string;
   readonly directory: string;
   readonly git: boolean;
   readonly install: boolean;
 }
 
-export interface NewProjectResult {
+export interface NewAppResult {
   readonly directory: string;
   readonly gitInitialized: boolean;
   readonly packageManager: PackageManager | null;
-  readonly projectName: string;
+  readonly appName: string;
 }
 
-export class ProjectDirectoryNotEmpty extends Schema.TaggedError<ProjectDirectoryNotEmpty>()(
-  "ProjectDirectoryNotEmpty",
+export class AppDirectoryNotEmpty extends Schema.TaggedError<AppDirectoryNotEmpty>()(
+  "AppDirectoryNotEmpty",
   {
     message: Schema.String,
     path: Schema.String,
   },
 ) {}
 
-export class InvalidProjectName extends Schema.TaggedError<InvalidProjectName>()(
-  "InvalidProjectName",
-  {
-    message: Schema.String,
-    path: Schema.String,
-  },
-) {}
+export class InvalidAppName extends Schema.TaggedError<InvalidAppName>()("InvalidAppName", {
+  message: Schema.String,
+  path: Schema.String,
+}) {}
 
 export class GitInitializationFailed extends Schema.TaggedError<GitInitializationFailed>()(
   "GitInitializationFailed",
@@ -44,12 +41,12 @@ export class GitInitializationFailed extends Schema.TaggedError<GitInitializatio
   },
 ) {}
 
-const packageJson = (projectName: string): string =>
+const packageJson = (appName: string): string =>
   `${JSON.stringify(
     {
-      name: projectName,
+      name: appName,
       private: true,
-      version: "0.0.0",
+      version: "1.0.0",
       type: "module",
       scripts: {
         typecheck: "ignotum codegen && tsc --noEmit",
@@ -138,12 +135,12 @@ export const increment = mutation({
 });
 `;
 
-const app = `import { Result, useMutation, useQuery } from "ignotum/client";
+const app = `import { app, Result, useMutation, useQuery } from "ignotum/client";
 
 import { api } from "@/_generated/api.js";
 import { counterIncrement } from "@/shared/utils.js";
 
-export default function App() {
+function App() {
   const count = useQuery(api.counter.get);
   const increment = useMutation(api.counter.increment);
 
@@ -168,22 +165,30 @@ export default function App() {
     </main>
   );
 }
+
+export default app({
+  title: "Counter",
+  component: App,
+});
 `;
 
-const utils = `export const counterIncrement = 1;
+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" />
+</svg>
 `;
 
-const styles = `@import "tailwindcss";
+const utils = `export const counterIncrement = 1;
 `;
 
-const readme = (projectName: string): string => `# ${projectName}
+const readme = (appName: string): string => `# ${appName}
 
 A small Ignotum counter app.
 
 ## Getting started
 
-You need Node.js 22.18 or newer. The project generator installs dependencies by default. If you
-created the project with \`--no-install\`, install them now:
+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:
 
 \`\`\`sh
 npx ignotum install
@@ -199,15 +204,16 @@ npx ignotum dev
 
 Open <http://127.0.0.1:3210>.
 
-The project generator creates \`_generated\`. The dev server checks those files before it starts
+The app generator creates \`_generated\`. The dev server checks those files before it starts
 and updates them when the schema or server functions change.
 
-## Project files
+## App files
 
 - \`server/schema.ts\` defines the database tables.
 - \`server/counter.ts\` defines the query and mutation used by the counter.
-- \`client/App.tsx\` is the UI.
-- \`client/styles.css\` loads Tailwind CSS.
+- \`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.
 
@@ -221,43 +227,43 @@ npx tsc --noEmit
 ## Claude Code
 
 If you use Claude Code, rename \`AGENTS.md\` to \`CLAUDE.md\` and \`.agents\` to \`.claude\` so it
-can find the project instructions and Ignotum skill.
+can find the app instructions and Ignotum skill.
 `;
 
-const projectFiles = (projectName: string): ReadonlyArray<ProjectFile> => [
-  { content: app, path: "client/App.tsx" },
-  { content: styles, path: "client/styles.css" },
+const appFiles = (appName: string): ReadonlyArray<AppFile> => [
+  { content: app, path: "client/index.tsx" },
+  { content: icon, path: "client/icon.svg" },
   { content: counterFunctions, path: "server/counter.ts" },
   { content: schema, path: "server/schema.ts" },
   { content: utils, path: "shared/utils.ts" },
-  { content: packageJson(projectName), path: "package.json" },
+  { content: packageJson(appName), path: "package.json" },
   { content: tsconfig, path: "tsconfig.json" },
   { content: gitignore, path: ".gitignore" },
-  { content: readme(projectName), path: "README.md" },
-  ...agentProjectFiles,
+  { content: readme(appName), path: "README.md" },
+  ...agentAppFiles,
 ];
 
-const writeProjectFile = Effect.fn("NewProject.writeProjectFile")(function* (
-  projectDirectory: string,
-  file: ProjectFile,
+const writeAppFile = Effect.fn("NewApp.writeAppFile")(function* (
+  appDirectory: string,
+  file: AppFile,
 ) {
   const fileSystem = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
-  const filePath = path.join(projectDirectory, file.path);
+  const filePath = path.join(appDirectory, file.path);
 
   yield* fileSystem.makeDirectory(path.dirname(filePath), { recursive: true });
   yield* fileSystem.writeFileString(filePath, file.content, { flag: "wx" });
 });
 
-const gitExitCode = Effect.fn("NewProject.gitExitCode")(function* (
-  projectDirectory: string,
+const gitExitCode = Effect.fn("NewApp.gitExitCode")(function* (
+  appDirectory: string,
   args: ReadonlyArray<string>,
 ) {
   const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
   return yield* spawner
     .exitCode(
       ChildProcess.make("git", args, {
-        cwd: projectDirectory,
+        cwd: appDirectory,
         stderr: "ignore",
         stdout: "ignore",
       }),
@@ -266,36 +272,36 @@ const gitExitCode = Effect.fn("NewProject.gitExitCode")(function* (
       Effect.mapError((cause) =>
         GitInitializationFailed.make({
           cause,
-          message: `Could not run Git in ${projectDirectory}.`,
-          path: projectDirectory,
+          message: `Could not run Git in ${appDirectory}.`,
+          path: appDirectory,
         }),
       ),
     );
 });
 
-const runGit = Effect.fn("NewProject.runGit")(function* (
-  projectDirectory: string,
+const runGit = Effect.fn("NewApp.runGit")(function* (
+  appDirectory: string,
   args: ReadonlyArray<string>,
   action: string,
 ) {
-  const exitCode = yield* gitExitCode(projectDirectory, args);
+  const exitCode = yield* gitExitCode(appDirectory, args);
 
   if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
     return yield* GitInitializationFailed.make({
-      message: `Git exited with code ${exitCode} while ${action} in ${projectDirectory}.`,
-      path: projectDirectory,
+      message: `Git exited with code ${exitCode} while ${action} in ${appDirectory}.`,
+      path: appDirectory,
     });
   }
 });
 
-const initializeGit = Effect.fn("NewProject.initializeGit")(function* (projectDirectory: string) {
-  yield* runGit(projectDirectory, ["init", "--quiet"], "initializing the repository");
-  yield* runGit(projectDirectory, ["add", "--all"], "staging the initial files");
+const initializeGit = Effect.fn("NewApp.initializeGit")(function* (appDirectory: string) {
+  yield* runGit(appDirectory, ["init", "--quiet"], "initializing the repository");
+  yield* runGit(appDirectory, ["add", "--all"], "staging the initial files");
 
   const [hasName, hasEmail] = yield* Effect.all(
     [
-      gitExitCode(projectDirectory, ["config", "user.name"]),
-      gitExitCode(projectDirectory, ["config", "user.email"]),
+      gitExitCode(appDirectory, ["config", "user.name"]),
+      gitExitCode(appDirectory, ["config", "user.email"]),
     ],
     { concurrency: "unbounded" },
   ).pipe(
@@ -309,69 +315,63 @@ const initializeGit = Effect.fn("NewProject.initializeGit")(function* (projectDi
       : ["-c", "user.name=Ignotum", "-c", "user.email=ignotum@localhost"];
 
   yield* runGit(
-    projectDirectory,
+    appDirectory,
     [...identity, "commit", "--quiet", "--no-gpg-sign", "-m", "Init"],
     "creating the initial commit",
   );
 });
 
-export const createProject = Effect.fn("NewProject.createProject")(function* (
-  options: NewProjectOptions,
-) {
+export const createApp = Effect.fn("NewApp.createApp")(function* (options: NewAppOptions) {
   const fileSystem = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
-  const projectDirectory = path.resolve(options.currentDirectory, options.directory);
-  const projectName = String.kebabCase(path.basename(projectDirectory));
+  const appDirectory = path.resolve(options.currentDirectory, options.directory);
+  const appName = String.kebabCase(path.basename(appDirectory));
 
-  if (projectName.length === 0) {
-    return yield* InvalidProjectName.make({
-      message: `Could not derive a package name from ${projectDirectory}.`,
-      path: projectDirectory,
+  if (appName.length === 0) {
+    return yield* InvalidAppName.make({
+      message: `Could not derive a package name from ${appDirectory}.`,
+      path: appDirectory,
     });
   }
 
-  const exists = yield* fileSystem.exists(projectDirectory);
+  const exists = yield* fileSystem.exists(appDirectory);
 
   if (exists) {
-    const info = yield* fileSystem.stat(projectDirectory);
+    const info = yield* fileSystem.stat(appDirectory);
     if (info.type !== "Directory") {
-      return yield* ProjectDirectoryNotEmpty.make({
-        message: `${projectDirectory} already exists and is not an empty directory.`,
-        path: projectDirectory,
+      return yield* AppDirectoryNotEmpty.make({
+        message: `${appDirectory} already exists and is not an empty directory.`,
+        path: appDirectory,
       });
     }
 
-    const entries = yield* fileSystem.readDirectory(projectDirectory);
+    const entries = yield* fileSystem.readDirectory(appDirectory);
     if (entries.length > 0) {
-      return yield* ProjectDirectoryNotEmpty.make({
-        message: `${projectDirectory} is not empty. Choose an empty directory.`,
-        path: projectDirectory,
+      return yield* AppDirectoryNotEmpty.make({
+        message: `${appDirectory} is not empty. Choose an empty directory.`,
+        path: appDirectory,
       });
     }
   } else {
-    yield* fileSystem.makeDirectory(projectDirectory, { recursive: true });
+    yield* fileSystem.makeDirectory(appDirectory, { recursive: true });
   }
 
-  yield* Effect.forEach(
-    projectFiles(projectName),
-    (file) => writeProjectFile(projectDirectory, file),
-    {
-      discard: true,
-    },
-  );
+  yield* Effect.forEach(appFiles(appName), (file) => writeAppFile(appDirectory, file), {
+    discard: true,
+  });
 
-  yield* generate(projectDirectory);
+  yield* generate(appDirectory);
 
-  const packageManager = options.install ? yield* installDependencies(projectDirectory) : null;
+  const packageManager = options.install ? yield* installDependencies(appDirectory) : null;
 
   if (options.git) {
-    yield* initializeGit(projectDirectory);
+    yield* initializeGit(appDirectory);
   }
 
   return {
-    directory: projectDirectory,
+    directory: appDirectory,
     gitInitialized: options.git,
     packageManager,
-    projectName,
-  } satisfies NewProjectResult;
+    appName,
+  } satisfies NewAppResult;
 });

package/src/cli/package-manager.ts

@@ -13,13 +13,13 @@ export class DependencyInstallationFailed extends Schema.TaggedError<DependencyI
 ) {}
 
 const installWith = Effect.fn("PackageManager.installWith")(function* (
-  projectDirectory: string,
+  appDirectory: string,
   packageManager: PackageManager,
 ) {
   const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
   const exitCode = yield* spawner.exitCode(
     ChildProcess.make(packageManager, ["install"], {
-      cwd: projectDirectory,
+      cwd: appDirectory,
       stderr: "inherit",
       stdin: "inherit",
       stdout: "inherit",
@@ -28,8 +28,8 @@ const installWith = Effect.fn("PackageManager.installWith")(function* (
 
   if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
     return yield* DependencyInstallationFailed.make({
-      message: `${packageManager} install exited with code ${exitCode} in ${projectDirectory}.`,
-      path: projectDirectory,
+      message: `${packageManager} install exited with code ${exitCode} in ${appDirectory}.`,
+      path: appDirectory,
     });
   }
 
@@ -37,18 +37,18 @@ const installWith = Effect.fn("PackageManager.installWith")(function* (
 });
 
 export const installDependencies = Effect.fn("PackageManager.installDependencies")(function* (
-  projectDirectory: string,
+  appDirectory: string,
 ) {
-  return yield* installWith(projectDirectory, "pnpm").pipe(
+  return yield* installWith(appDirectory, "pnpm").pipe(
     Effect.catchReasons("PlatformError", {
-      NotFound: () => installWith(projectDirectory, "npm"),
+      NotFound: () => installWith(appDirectory, "npm"),
     }),
     Effect.catchTags({
       PlatformError: (cause) =>
         DependencyInstallationFailed.make({
           cause,
-          message: `Could not run pnpm or npm in ${projectDirectory}.`,
-          path: projectDirectory,
+          message: `Could not run pnpm or npm in ${appDirectory}.`,
+          path: appDirectory,
         }),
     }),
   );

package/src/client/app.ts

@@ -0,0 +1,15 @@
+import type { ComponentType } from "preact";
+
+export interface AppDefinition<Component extends ComponentType<{}> = ComponentType<{}>> {
+  readonly component: Component;
+  readonly title: string;
+}
+
+export const app = <Component extends ComponentType<{}>>(
+  definition: AppDefinition<Component>,
+): AppDefinition<Component> => {
+  if (definition.title.trim().length === 0) {
+    throw new Error("The app title must contain a non-whitespace character.");
+  }
+  return definition;
+};

package/src/client/errors.ts

@@ -1,12 +1,7 @@
 /** @effect-diagnostics globalConsole:skip-file */
 import { Cause, Effect, ErrorReporter, Schema } from "effect";
 
-import {
-  FunctionAddress,
-  Operation,
-  ProtocolErrorCode,
-  RequestId,
-} from "@ignotum/contracts/runtime/sync";
+import { FunctionAddress, Operation, ProtocolErrorCode } from "@ignotum/contracts/runtime/sync";
 
 export class ConnectionUnavailable extends Schema.TaggedError<ConnectionUnavailable>()(
   "ConnectionUnavailable",
@@ -50,23 +45,12 @@ export class ServerProtocolError extends Schema.TaggedError<ServerProtocolError>
   },
 ) {}
 
-export class MutationOutcomeUnknown extends Schema.TaggedError<MutationOutcomeUnknown>()(
-  "MutationOutcomeUnknown",
-  {
-    cause: Schema.optional(Schema.Defect()),
-    function: FunctionAddress,
-    id: RequestId,
-    message: Schema.String,
-  },
-) {}
-
 export const ClientInfrastructureError = Schema.Union([
   ConnectionUnavailable,
   InvalidClientMessage,
   InvalidMutationArguments,
   InvalidServerMessage,
   ServerProtocolError,
-  MutationOutcomeUnknown,
 ]);
 export type ClientInfrastructureError = typeof ClientInfrastructureError.Type;
 

package/src/client/index.ts

@@ -12,6 +12,8 @@ export type { InternalServerError } from "@ignotum/contracts/runtime/result";
 export { useMutation, useQuery } from "./hooks.js";
 export { Query } from "./query.js";
 export type { QuerySkip } from "./query.js";
+export { app } from "./app.js";
+export type { AppDefinition } from "./app.js";
 
 export {
   Component,