apps 0.8.2 → 1.0.0-beta.0

package/src/manifest/index.ts

@@ -0,0 +1,224 @@
+/**
+ * Manifest: execute an authored app folder, read its registry, validate
+ * every claim, and emit the deterministic publish manifest. Defines run
+ * without user context; platform services begin at this boundary.
+ */
+
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { Crypto, Effect, FileSystem, Schema, Semaphore } from "effect";
+import {
+  __enterFile,
+  __leaveFile,
+  newRegistry,
+  setActiveRegistry,
+  type Registry,
+} from "../authoring/index";
+import { collectRegistry, type InputSchemaCompilation } from "./collect";
+import {
+  JsonSchemaObject,
+  PublishError,
+  type AppManifestResult,
+  type JsonSchemaObject as JsonSchemaObjectType,
+} from "./contract";
+
+export * from "./contract";
+
+interface StandardJsonSchemaCapable {
+  readonly "~standard": {
+    readonly jsonSchema?: {
+      readonly input: (options: { readonly target: string }) => unknown;
+    };
+  };
+}
+
+const hasStandardJsonSchema = (input: object): input is StandardJsonSchemaCapable =>
+  "~standard" in input &&
+  typeof (input as StandardJsonSchemaCapable)["~standard"].jsonSchema?.input === "function";
+
+const compileInputSchema = (
+  input: object,
+  where: string,
+): InputSchemaCompilation => {
+  if ("~standard" in input) {
+    if (!hasStandardJsonSchema(input))
+      return {
+        problem: `${where}: input is a Standard Schema without the jsonSchema extension — use a library that implements it (zod 4+, effect Schema) or pass raw JSON schema`,
+      };
+  }
+
+  try {
+    const compiled = strictify(
+      hasStandardJsonSchema(input)
+        ? input["~standard"].jsonSchema!.input({ target: "draft-2020-12" })
+        : structuredClone(input),
+    );
+    return { value: Schema.decodeUnknownSync(JsonSchemaObject)(compiled) as JsonSchemaObjectType };
+  } catch (error) {
+    return { problem: schemaPublishProblem(where, error) };
+  }
+};
+
+const schemaPublishProblem = (where: string, error: unknown): string =>
+  `${where}: input schema could not compile to JSON schema (${
+    error instanceof Error ? error.message : String(error)
+  })`;
+
+const strictify = (node: unknown): unknown => {
+  if (typeof node !== "object" || node === null) return node;
+  if (Array.isArray(node)) return node.map(strictify);
+  const object = { ...(node as Record<string, unknown>) };
+  if (object.type === "object" && object.additionalProperties === undefined)
+    object.additionalProperties = false;
+  for (const key of ["items", "anyOf", "oneOf", "allOf"])
+    if (key in object) object[key] = strictify(object[key]);
+  for (const key of ["properties", "$defs"])
+    if (object[key] !== undefined && typeof object[key] === "object" && object[key] !== null)
+      object[key] = Object.fromEntries(
+        Object.entries(object[key] as Record<string, unknown>).map(([name, value]) => [
+          name,
+          strictify(value),
+        ]),
+      );
+  return object;
+};
+
+const digestOf = (content: string): Effect.Effect<string, never, Crypto.Crypto> =>
+  Effect.gen(function* () {
+    const crypto = yield* Crypto.Crypto;
+    const bytes = yield* Effect.orDie(
+      crypto.digest("SHA-256", new TextEncoder().encode(content)),
+    );
+    return Array.from(bytes.slice(0, 8), (byte) => byte.toString(16).padStart(2, "0")).join("");
+  });
+
+const loadPermit = Semaphore.makeUnsafe(1);
+let runNonce = 0;
+const baseAppImports = new Set<string>();
+
+const moduleFailure = (where: string, error: unknown): PublishError =>
+  new PublishError({
+    problems: [
+      `${where}: failed to execute (${error instanceof Error ? error.message : String(error)})`,
+    ],
+  });
+
+const canonicalModuleUrl = (
+  path: string,
+  where: string,
+): Effect.Effect<URL, PublishError, FileSystem.FileSystem> =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const realPath = yield* fs.realPath(path).pipe(
+      Effect.mapError((error) => moduleFailure(where, error)),
+    );
+    return pathToFileURL(realPath);
+  });
+
+const importModule = (specifier: string, where: string): Effect.Effect<void, PublishError> =>
+  Effect.tryPromise({
+    try: () => import(specifier).then(() => undefined),
+    catch: (error) => moduleFailure(where, error),
+  });
+
+const recordModuleProblems = (
+  registry: Registry,
+  effect: Effect.Effect<void, PublishError, FileSystem.FileSystem>,
+): Effect.Effect<void, never, FileSystem.FileSystem> =>
+  effect.pipe(
+    Effect.catchTag("PublishError", (error) =>
+      Effect.sync(() => {
+        registry.problems.push(...error.problems.map((message) => ({ message })));
+      }),
+    ),
+  );
+
+const executeModules = (
+  appDir: string,
+  files: readonly string[],
+): Effect.Effect<Registry, never, FileSystem.FileSystem> =>
+  loadPermit.withPermit(
+    Effect.uninterruptibleMask((restore) =>
+      Effect.gen(function* () {
+        const registry = newRegistry();
+        const previous = yield* Effect.sync(() => setActiveRegistry(registry));
+        const nonce = yield* Effect.sync(() => ++runNonce);
+
+        const execute = Effect.gen(function* () {
+          __enterFile("app.ts");
+          yield* recordModuleProblems(
+            registry,
+            Effect.gen(function* () {
+              const appUrl = yield* canonicalModuleUrl(`${appDir}/app.ts`, "app.ts");
+              const baseUrl = appUrl.href;
+              const specifier = baseAppImports.has(baseUrl)
+                ? `${fileURLToPath(appUrl)}?m=${nonce}`
+                : baseUrl;
+              yield* importModule(specifier, "app.ts");
+              yield* Effect.sync(() => baseAppImports.add(baseUrl));
+            }),
+          );
+
+          for (const file of files) {
+            const where = `tools/${file}`;
+            __enterFile(where);
+            yield* recordModuleProblems(
+              registry,
+              Effect.gen(function* () {
+                const url = yield* canonicalModuleUrl(`${appDir}/tools/${file}`, where);
+                yield* importModule(`${fileURLToPath(url)}?m=${nonce}`, where);
+              }),
+            );
+          }
+        });
+
+        yield* restore(execute).pipe(
+          Effect.ensuring(
+            Effect.sync(() => {
+              __leaveFile();
+              setActiveRegistry(previous);
+            }),
+          ),
+        );
+        return registry;
+      }),
+    ),
+  );
+
+/** A registry and its validated public projection. @internal */
+export interface LoadedApp {
+  readonly registry: Registry;
+  readonly result: AppManifestResult;
+}
+
+/** Loads an app once and returns both its live registry and manifest. @internal */
+export const loadApp = (
+  appDir: string,
+): Effect.Effect<LoadedApp, PublishError, Crypto.Crypto | FileSystem.FileSystem> =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const files = (yield* fs.readDirectory(`${appDir}/tools`).pipe(
+      Effect.mapError((error) => new PublishError({ problems: [`tools/: ${error.message}`] })),
+    ))
+      .filter((file) => file.endsWith(".ts"))
+      .sort();
+    const registry = yield* executeModules(appDir, files);
+    const collected = collectRegistry(registry, compileInputSchema);
+    if (collected.problems.length > 0)
+      return yield* new PublishError({ problems: collected.problems });
+    if (!("manifest" in collected))
+      return yield* Effect.die("validated registry projection unexpectedly missing");
+
+    return {
+      registry,
+      result: {
+        digest: `snap:${yield* digestOf(collected.canonical)}`,
+        ...collected.manifest,
+      },
+    };
+  });
+
+/** Executes an app and returns its deterministic publish manifest. */
+export const manifest = (
+  appDir: string,
+): Effect.Effect<AppManifestResult, PublishError, Crypto.Crypto | FileSystem.FileSystem> =>
+  Effect.map(loadApp(appDir), ({ result }) => result);

package/src/runner/index.ts

@@ -0,0 +1,117 @@
+import { Crypto, Effect, FileSystem } from "effect";
+import type { ToolSpec } from "../authoring/index";
+import {
+  loadApp,
+  type LoadedApp,
+  type PublishError,
+} from "../manifest/index";
+import { CallError, type AppRunner, type ToolCtx } from "./protocol";
+
+export * from "./protocol";
+
+interface StandardSchemaCapable {
+  readonly "~standard": {
+    readonly validate: (
+      value: unknown,
+    ) =>
+      | { readonly value: unknown; readonly issues?: undefined }
+      | { readonly issues: ReadonlyArray<{ readonly message: string }> }
+      | Promise<
+          | { readonly value: unknown; readonly issues?: undefined }
+          | { readonly issues: ReadonlyArray<{ readonly message: string }> }
+        >;
+  };
+}
+
+const hasStandardValidate = (input: object): input is StandardSchemaCapable =>
+  "~standard" in input &&
+  typeof (input as StandardSchemaCapable)["~standard"].validate === "function";
+
+const parseInput = (name: string, spec: ToolSpec, input: unknown): Effect.Effect<unknown, CallError> => {
+  if (!hasStandardValidate(spec.input))
+    return Effect.fail(
+      new CallError({ target: name, reason: "input schema does not implement Standard Schema validate" }),
+    );
+  const standard = spec.input["~standard"];
+
+  return Effect.tryPromise({
+    try: () => Promise.resolve(standard.validate(input)),
+    catch: (error) =>
+      new CallError({
+        target: name,
+        reason: `input validation threw (${error instanceof Error ? error.message : String(error)})`,
+      }),
+  }).pipe(
+    Effect.flatMap((result) =>
+      result.issues === undefined
+        ? Effect.succeed(result.value)
+        : Effect.fail(
+            new CallError({
+              target: name,
+              reason: `invalid input (${result.issues.map((issue) => issue.message).join("; ")})`,
+            }),
+          ),
+    ),
+  );
+};
+
+/** Creates a permissive in-process runner for local development and tests. */
+export const localRunner = (appDir: string): AppRunner => {
+  let cachedLoad: Effect.Effect<
+    LoadedApp,
+    PublishError,
+    Crypto.Crypto | FileSystem.FileSystem
+  > | undefined;
+
+  const loaded = (): Effect.Effect<
+    LoadedApp,
+    PublishError,
+    Crypto.Crypto | FileSystem.FileSystem
+  > =>
+    Effect.suspend(() => {
+      if (cachedLoad !== undefined) return cachedLoad;
+      return Effect.flatMap(Effect.cached(loadApp(appDir)), (effect) =>
+        Effect.sync(() => {
+          cachedLoad = effect;
+          return effect;
+        }).pipe(Effect.flatten),
+      );
+    });
+
+  const loadedFor = (
+    target: string,
+  ): Effect.Effect<LoadedApp, CallError, Crypto.Crypto | FileSystem.FileSystem> =>
+    loaded().pipe(
+      Effect.mapError(
+        (error) => new CallError({ target, reason: `app failed to load (${error.message})` }),
+      ),
+    );
+
+  return {
+    manifest: () => Effect.map(loaded(), ({ result }) => result),
+    call: (name, input, ctx) =>
+      Effect.gen(function* () {
+        const { registry } = yield* loadedFor(name);
+        const registered = registry.tools.get(name);
+        if (registered === undefined)
+          return yield* new CallError({ target: name, reason: "unknown tool" });
+        const parsed = yield* parseInput(name, registered.spec, input);
+        return yield* Effect.tryPromise({
+          // SAFETY: ToolSpec intentionally erases authored handler inputs to keep
+          // authoring generic-free; validation and ToolCtx establish this call boundary.
+          try: () =>
+            (registered.spec.handler as (value: unknown, toolCtx: ToolCtx) => Promise<unknown>)(
+              parsed,
+              ctx,
+            ),
+          catch: (error) =>
+            new CallError({
+              target: name,
+              reason: `handler failed (${error instanceof Error ? error.message : String(error)})`,
+            }),
+        });
+      }),
+    discover: (name, _binding) =>
+      Effect.fail(new CallError({ target: name, reason: "no dynamic tools yet" })),
+  };
+};

package/src/runner/protocol.ts

@@ -0,0 +1,41 @@
+import { Crypto, Data, type Effect, FileSystem } from "effect";
+import type { AppManifestResult, PublishError } from "../manifest/contract";
+
+/** The capability exposed to one tool requirement role. */
+export interface ToolCtxEntry {
+  readonly grant: string;
+  readonly token?: string;
+  readonly secrets?: Readonly<Record<string, string>>;
+  fetch(path: string, init?: RequestInit): Promise<Response>;
+}
+
+/** Tool capabilities keyed by requirement role. */
+export type ToolCtx = Readonly<Record<string, ToolCtxEntry>>;
+
+/** A runner operation failure associated with its target. */
+export class CallError extends Data.TaggedError("CallError")<{
+  readonly target: string;
+  readonly reason: string;
+}> {
+  override get message(): string {
+    return `${this.target}: ${this.reason}`;
+  }
+}
+
+/** The platform protocol implemented by an app execution environment. */
+export interface AppRunner {
+  manifest(): Effect.Effect<
+    AppManifestResult,
+    PublishError,
+    Crypto.Crypto | FileSystem.FileSystem
+  >;
+  call(
+    name: string,
+    input: unknown,
+    ctx: ToolCtx,
+  ): Effect.Effect<unknown, CallError, Crypto.Crypto | FileSystem.FileSystem>;
+  discover(
+    name: string,
+    binding: unknown,
+  ): Effect.Effect<unknown, CallError, Crypto.Crypto | FileSystem.FileSystem>;
+}

package/src/workerd/index.ts

@@ -0,0 +1,2 @@
+/** Worker-safe registry projection injected into sandboxed app workers. @internal */
+export { collectRegistry } from "../manifest/collect";

package/.npmignore

@@ -1 +0,0 @@
-node_modules

package/bin/apps

@@ -1,36 +0,0 @@
-#!/usr/bin/env node
-
-var program = require("commander")
-var pkg = require("../package.json")
-var marked = require('marked')
-var App = require("..")
-
-program
-  .version(pkg.version)
-
-program
-  .command("schema")
-  .option('--markdown', 'Write the schema in markdown format')
-  .option('--html', 'Write the schema in HTML format')
-  .description("Write the app.json schema to STDOUT")
-  .action(function(program){
-    if (program.markdown) {
-      process.stdout.write(App.templates.schema.render(App.schema))
-    } else if (program.html) {
-      process.stdout.write(marked(App.templates.schema.render(App.schema)))
-    } else {
-      process.stdout.write(JSON.stringify(App.schema.properties, null, 2))
-    }
-  })
-
-// Print this after the generated help text
-program.on("--help", function(){
-  console.log("  Use 'app <command> --help' to get more information about a specific command.")
-  console.log('')
-})
-
-program.parse(process.argv)
-
-if(program.args.length < 1){
-  program.help()
-}

package/bin/build

@@ -1,14 +0,0 @@
-#!/usr/bin/env bash
-
-echo "window.App = require('./')" \
-  | node_modules/browserify/bin/cmd.js --transform browserify-hogan --transform brfs \
-  > dist/app.js
-
-echo "Wrote dist/app.js"
-
-echo "window.App = require('./')" \
-  | node_modules/browserify/bin/cmd.js --transform browserify-hogan --transform brfs \
-  | node_modules/uglify-js/bin/uglifyjs \
-  > dist/app.min.js
-
-echo "Wrote dist/app.min.js"

package/bin/doc

@@ -1,16 +0,0 @@
-#!/usr/bin/env node
-
-var fs = require("fs")
-var marked = require('marked')
-var App = require('..')
-var out = App.templates.schema.render(App.schema)
-
-fs.writeFile("./dist/schema.md", out, function(err) {
-  if (err) return console.error(err)
-  console.log("Wrote dist/schema.md")
-
-  fs.writeFile("./dist/schema.html", marked(out), function(err) {
-    if (err) return console.error(err)
-    console.log("Wrote dist/schema.html")
-  })
-})