ignotum 0.0.0 → 0.0.2

package/src/cli/new-project.ts

@@ -0,0 +1,377 @@
+import { Effect, FileSystem, Path, Schema, String } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import { agentProjectFiles, type ProjectFile } from "./agent-files.js";
+import { generate } from "./codegen.js";
+import { installDependencies, type PackageManager } from "./package-manager.js";
+
+export interface NewProjectOptions {
+  readonly currentDirectory: string;
+  readonly directory: string;
+  readonly git: boolean;
+  readonly install: boolean;
+}
+
+export interface NewProjectResult {
+  readonly directory: string;
+  readonly gitInitialized: boolean;
+  readonly packageManager: PackageManager | null;
+  readonly projectName: string;
+}
+
+export class ProjectDirectoryNotEmpty extends Schema.TaggedError<ProjectDirectoryNotEmpty>()(
+  "ProjectDirectoryNotEmpty",
+  {
+    message: Schema.String,
+    path: Schema.String,
+  },
+) {}
+
+export class InvalidProjectName extends Schema.TaggedError<InvalidProjectName>()(
+  "InvalidProjectName",
+  {
+    message: Schema.String,
+    path: Schema.String,
+  },
+) {}
+
+export class GitInitializationFailed extends Schema.TaggedError<GitInitializationFailed>()(
+  "GitInitializationFailed",
+  {
+    cause: Schema.optional(Schema.Defect()),
+    message: Schema.String,
+    path: Schema.String,
+  },
+) {}
+
+const packageJson = (projectName: string): string =>
+  `${JSON.stringify(
+    {
+      name: projectName,
+      private: true,
+      version: "0.0.0",
+      type: "module",
+      scripts: {
+        typecheck: "ignotum codegen && tsc --noEmit",
+      },
+      dependencies: {
+        ignotum: "latest",
+      },
+      devDependencies: {
+        typescript: "^7.0.2",
+      },
+      engines: {
+        node: ">=22.18.0",
+      },
+    },
+    null,
+    2,
+  )}\n`;
+
+const tsconfig = `{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "jsx": "react-jsx",
+    "jsxImportSource": "ignotum/client",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["_generated", "client", "server", "shared"]
+}
+`;
+
+const gitignore = `node_modules/
+.ignotum/
+
+.env
+.env.*
+!.env.example
+
+.DS_Store
+Thumbs.db
+`;
+
+const schema = `import { defineSchema } from "ignotum/server";
+
+export default defineSchema(({ table, values }) => ({
+  counters: table({
+    value: values.number(),
+  }),
+}));
+`;
+
+const counterFunctions = `import { mutation, query, values } from "@/_generated/server.js";
+import { counterIncrement } from "@/shared/utils.js";
+
+export const get = query({
+  returns: values.number(),
+
+  handler: function* (ctx) {
+    const counters = yield* ctx.db.query("counters").collect();
+    return counters[0]?.value ?? 0;
+  },
+});
+
+export const increment = mutation({
+  returns: values.number(),
+
+  handler: function* (ctx) {
+    const counters = yield* ctx.db.query("counters").collect();
+    const counter = counters[0];
+    const value = (counter?.value ?? 0) + counterIncrement;
+
+    if (counter === undefined) {
+      yield* ctx.db.insert("counters", { value });
+    } else {
+      yield* ctx.db.patch("counters", counter.id, { value });
+    }
+
+    return value;
+  },
+});
+`;
+
+const app = `import { Result, useMutation, useQuery } from "ignotum/client";
+
+import { api } from "@/_generated/api.js";
+import { counterIncrement } from "@/shared/utils.js";
+
+export default 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>
+  );
+}
+`;
+
+const utils = `export const counterIncrement = 1;
+`;
+
+const styles = `@import "tailwindcss";
+`;
+
+const readme = (projectName: string): string => `# ${projectName}
+
+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:
+
+\`\`\`sh
+npx ignotum install
+\`\`\`
+
+This command uses pnpm when it is installed and otherwise uses npm.
+
+Start the app:
+
+\`\`\`sh
+npx ignotum dev
+\`\`\`
+
+Open <http://127.0.0.1:3210>.
+
+The project generator creates \`_generated\`. The dev server checks those files before it starts
+and updates them when the schema or server functions change.
+
+## Project 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.
+- \`shared/utils.ts\` contains code shared across the app.
+- \`_generated\` contains Ignotum's generated types and bindings. Do not edit it by hand.
+
+Run the typechecker after a change:
+
+\`\`\`sh
+npx ignotum codegen
+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.
+`;
+
+const projectFiles = (projectName: string): ReadonlyArray<ProjectFile> => [
+  { content: app, path: "client/App.tsx" },
+  { content: styles, path: "client/styles.css" },
+  { 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: tsconfig, path: "tsconfig.json" },
+  { content: gitignore, path: ".gitignore" },
+  { content: readme(projectName), path: "README.md" },
+  ...agentProjectFiles,
+];
+
+const writeProjectFile = Effect.fn("NewProject.writeProjectFile")(function* (
+  projectDirectory: string,
+  file: ProjectFile,
+) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const filePath = path.join(projectDirectory, 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,
+  args: ReadonlyArray<string>,
+) {
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  return yield* spawner
+    .exitCode(
+      ChildProcess.make("git", args, {
+        cwd: projectDirectory,
+        stderr: "ignore",
+        stdout: "ignore",
+      }),
+    )
+    .pipe(
+      Effect.mapError((cause) =>
+        GitInitializationFailed.make({
+          cause,
+          message: `Could not run Git in ${projectDirectory}.`,
+          path: projectDirectory,
+        }),
+      ),
+    );
+});
+
+const runGit = Effect.fn("NewProject.runGit")(function* (
+  projectDirectory: string,
+  args: ReadonlyArray<string>,
+  action: string,
+) {
+  const exitCode = yield* gitExitCode(projectDirectory, args);
+
+  if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
+    return yield* GitInitializationFailed.make({
+      message: `Git exited with code ${exitCode} while ${action} in ${projectDirectory}.`,
+      path: projectDirectory,
+    });
+  }
+});
+
+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 [hasName, hasEmail] = yield* Effect.all(
+    [
+      gitExitCode(projectDirectory, ["config", "user.name"]),
+      gitExitCode(projectDirectory, ["config", "user.email"]),
+    ],
+    { concurrency: "unbounded" },
+  ).pipe(
+    Effect.map((exitCodes) =>
+      exitCodes.map((exitCode) => exitCode === ChildProcessSpawner.ExitCode(0)),
+    ),
+  );
+  const identity =
+    hasName === true && hasEmail === true
+      ? []
+      : ["-c", "user.name=Ignotum", "-c", "user.email=ignotum@localhost"];
+
+  yield* runGit(
+    projectDirectory,
+    [...identity, "commit", "--quiet", "--no-gpg-sign", "-m", "Init"],
+    "creating the initial commit",
+  );
+});
+
+export const createProject = Effect.fn("NewProject.createProject")(function* (
+  options: NewProjectOptions,
+) {
+  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));
+
+  if (projectName.length === 0) {
+    return yield* InvalidProjectName.make({
+      message: `Could not derive a package name from ${projectDirectory}.`,
+      path: projectDirectory,
+    });
+  }
+
+  const exists = yield* fileSystem.exists(projectDirectory);
+
+  if (exists) {
+    const info = yield* fileSystem.stat(projectDirectory);
+    if (info.type !== "Directory") {
+      return yield* ProjectDirectoryNotEmpty.make({
+        message: `${projectDirectory} already exists and is not an empty directory.`,
+        path: projectDirectory,
+      });
+    }
+
+    const entries = yield* fileSystem.readDirectory(projectDirectory);
+    if (entries.length > 0) {
+      return yield* ProjectDirectoryNotEmpty.make({
+        message: `${projectDirectory} is not empty. Choose an empty directory.`,
+        path: projectDirectory,
+      });
+    }
+  } else {
+    yield* fileSystem.makeDirectory(projectDirectory, { recursive: true });
+  }
+
+  yield* Effect.forEach(
+    projectFiles(projectName),
+    (file) => writeProjectFile(projectDirectory, file),
+    {
+      discard: true,
+    },
+  );
+
+  yield* generate(projectDirectory);
+
+  const packageManager = options.install ? yield* installDependencies(projectDirectory) : null;
+
+  if (options.git) {
+    yield* initializeGit(projectDirectory);
+  }
+
+  return {
+    directory: projectDirectory,
+    gitInitialized: options.git,
+    packageManager,
+    projectName,
+  } satisfies NewProjectResult;
+});

package/src/cli/package-manager.ts

@@ -0,0 +1,55 @@
+import { Effect, Schema } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+export type PackageManager = "npm" | "pnpm";
+
+export class DependencyInstallationFailed extends Schema.TaggedError<DependencyInstallationFailed>()(
+  "DependencyInstallationFailed",
+  {
+    cause: Schema.optional(Schema.Defect()),
+    message: Schema.String,
+    path: Schema.String,
+  },
+) {}
+
+const installWith = Effect.fn("PackageManager.installWith")(function* (
+  projectDirectory: string,
+  packageManager: PackageManager,
+) {
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const exitCode = yield* spawner.exitCode(
+    ChildProcess.make(packageManager, ["install"], {
+      cwd: projectDirectory,
+      stderr: "inherit",
+      stdin: "inherit",
+      stdout: "inherit",
+    }),
+  );
+
+  if (exitCode !== ChildProcessSpawner.ExitCode(0)) {
+    return yield* DependencyInstallationFailed.make({
+      message: `${packageManager} install exited with code ${exitCode} in ${projectDirectory}.`,
+      path: projectDirectory,
+    });
+  }
+
+  return packageManager;
+});
+
+export const installDependencies = Effect.fn("PackageManager.installDependencies")(function* (
+  projectDirectory: string,
+) {
+  return yield* installWith(projectDirectory, "pnpm").pipe(
+    Effect.catchReasons("PlatformError", {
+      NotFound: () => installWith(projectDirectory, "npm"),
+    }),
+    Effect.catchTags({
+      PlatformError: (cause) =>
+        DependencyInstallationFailed.make({
+          cause,
+          message: `Could not run pnpm or npm in ${projectDirectory}.`,
+          path: projectDirectory,
+        }),
+    }),
+  );
+});

package/src/client/errors.ts

@@ -0,0 +1,83 @@
+/** @effect-diagnostics globalConsole:skip-file */
+import { Cause, Effect, ErrorReporter, Schema } from "effect";
+
+import {
+  FunctionAddress,
+  Operation,
+  ProtocolErrorCode,
+  RequestId,
+} from "@ignotum/contracts/runtime/sync";
+
+export class ConnectionUnavailable extends Schema.TaggedError<ConnectionUnavailable>()(
+  "ConnectionUnavailable",
+  {
+    cause: Schema.optional(Schema.Defect()),
+    message: Schema.String,
+  },
+) {}
+
+export class InvalidClientMessage extends Schema.TaggedError<InvalidClientMessage>()(
+  "InvalidClientMessage",
+  {
+    cause: Schema.Defect(),
+    message: Schema.String,
+  },
+) {}
+
+export class InvalidMutationArguments extends Schema.TaggedError<InvalidMutationArguments>()(
+  "InvalidMutationArguments",
+  {
+    cause: Schema.Defect(),
+    function: FunctionAddress,
+    message: Schema.String,
+  },
+) {}
+
+export class InvalidServerMessage extends Schema.TaggedError<InvalidServerMessage>()(
+  "InvalidServerMessage",
+  {
+    cause: Schema.Defect(),
+    message: Schema.String,
+  },
+) {}
+
+export class ServerProtocolError extends Schema.TaggedError<ServerProtocolError>()(
+  "ServerProtocolError",
+  {
+    code: ProtocolErrorCode,
+    message: Schema.String,
+    operation: Schema.optional(Operation),
+  },
+) {}
+
+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;
+
+const browserErrorReporter = ErrorReporter.make(({ attributes, error }) => {
+  globalThis.console.error("Ignotum infrastructure error", error, attributes);
+});
+
+export const clientErrorReporterLayer = ErrorReporter.layer([browserErrorReporter]);
+
+export const reportClientError = Effect.fn("ClientErrorReporter.report")(function* (
+  error: ClientInfrastructureError,
+) {
+  yield* ErrorReporter.report(Cause.fail(error));
+});

package/src/client/hooks.ts

@@ -0,0 +1,141 @@
+import { Effect, Schema } from "effect";
+import { useDebugValue, useEffect, useMemo, useState } from "preact/hooks";
+
+import { functionPathOf, type FunctionReference } from "../internal/api.js";
+import { pending } from "@ignotum/contracts/runtime/result";
+import type { ErrorValue, QueryResult, SettledResult } from "@ignotum/contracts/runtime/result";
+import { encodeTransportObject } from "@ignotum/contracts/runtime/sync";
+import {
+  ClientInfrastructureError,
+  InvalidMutationArguments,
+  reportClientError,
+} from "./errors.js";
+import { isQuerySkip, type QuerySkip } from "./query.js";
+import { SyncClient, syncClientInternals, syncRuntime } from "./sync.js";
+
+// @effect-diagnostics-next-line missingPipeableSignature:off React hooks are not pipeable functions.
+export function useQuery<Success, Failure extends ErrorValue>(
+  reference: FunctionReference<"Query", void, Success, Failure>,
+): QueryResult<Success, Failure>;
+export function useQuery<Success, Failure extends ErrorValue>(
+  reference: FunctionReference<"Query", void, Success, Failure>,
+  args: QuerySkip,
+): QueryResult<Success, Failure>;
+export function useQuery<Args extends object, Success, Failure extends ErrorValue>(
+  reference: FunctionReference<"Query", Args, Success, Failure>,
+  args: NoInfer<Args> | QuerySkip,
+): QueryResult<Success, Failure>;
+// @effect-diagnostics-next-line missingPipeableSignature:off React hooks must remain direct calls so hook order is statically visible.
+export function useQuery<Args extends object, Success, Failure extends ErrorValue>(
+  reference: FunctionReference<"Query", Args | void, Success, Failure>,
+  args?: Args | QuerySkip,
+): QueryResult<Success, Failure> {
+  const functionPath = functionPathOf(reference);
+  const skipped = isQuerySkip(args);
+  const input = args === undefined || skipped ? {} : args;
+  const jsonArgs = encodeTransportObject(input);
+  const identity = skipped
+    ? `skip:${functionPath}`
+    : syncClientInternals.queryIdentity(functionPath, jsonArgs);
+  const [state, setState] = useState<{
+    readonly identity: string;
+    readonly result: QueryResult<Success, Failure> | ClientInfrastructureError;
+  }>(() => ({ identity, result: pending() }));
+
+  useDebugValue({ args: input, function: functionPath, result: state.result });
+  useEffect(() => {
+    if (skipped) return;
+
+    let active = true;
+    let release: (() => void) | undefined;
+
+    void syncRuntime
+      .runPromise(
+        Effect.gen(function* () {
+          const client = yield* SyncClient;
+          return yield* client.observe(functionPath, jsonArgs);
+        }),
+      )
+      .then(
+        (observer) => {
+          if (!active) {
+            syncRuntime.runFork(observer.release);
+            return;
+          }
+          const update = () => {
+            // SAFETY: the function reference couples this subscription's runtime
+            // path to its generated success and failure types.
+            const result = observer.getSnapshot() as
+              | QueryResult<Success, Failure>
+              | ClientInfrastructureError;
+            setState({ identity, result });
+          };
+          release = observer.subscribe(update);
+          update();
+          const releaseObserver = release;
+          release = () => {
+            releaseObserver();
+            syncRuntime.runFork(observer.release);
+          };
+        },
+        (error) => {
+          if (active && Schema.is(ClientInfrastructureError)(error)) {
+            setState({ identity, result: error });
+          }
+        },
+      );
+
+    return () => {
+      active = false;
+      release?.();
+    };
+  }, [identity]);
+
+  if (skipped) return pending();
+
+  if (state.identity !== identity) {
+    return pending();
+  }
+
+  const result = state.result;
+  if (Schema.is(ClientInfrastructureError)(result)) throw result;
+  return result;
+}
+
+type Mutation<Args, Success, Failure extends ErrorValue> = [Args] extends [void]
+  ? () => Promise<SettledResult<Success, Failure>>
+  : (args: Args) => Promise<SettledResult<Success, Failure>>;
+
+export const useMutation = <Args extends object | void, Success, Failure extends ErrorValue>(
+  reference: FunctionReference<"Mutation", Args, Success, Failure>,
+): Mutation<Args, Success, Failure> =>
+  useMemo(() => {
+    const mutate = (args: Args | undefined) => {
+      const functionPath = functionPathOf(reference);
+      const input = args === undefined ? {} : args;
+      return syncRuntime.runPromise<SettledResult<Success, Failure>, ClientInfrastructureError>(
+        Effect.gen(function* () {
+          const client = yield* SyncClient;
+          const jsonArgs = yield* Effect.try({
+            try: () => encodeTransportObject(input),
+            catch: (cause) =>
+              InvalidMutationArguments.make({
+                cause,
+                function: functionPath,
+                message: `Mutation arguments for ${functionPath} contain an unsupported value.`,
+              }),
+          }).pipe(Effect.tapError(reportClientError));
+          // SAFETY: generated function references bind the runtime path to the
+          // declared public result types validated by the server executor.
+          // oxlint-disable-next-line anti-slop/no-chained-type-assertions -- The untyped sync transport deliberately erases the generated reference's result parameters.
+          return (yield* client.mutate(functionPath, jsonArgs)) as unknown as SettledResult<
+            Success,
+            Failure
+          >;
+        }),
+      );
+    };
+    // SAFETY: the builder gives argument-free functions Args = void. At runtime
+    // both call shapes normalize omitted arguments to the empty JSON object.
+    return mutate as Mutation<Args, Success, Failure>;
+  }, [reference]);