apps 0.8.3 → 1.0.0-beta.1

package/dist/chunk-LWKQDDLZ.js

@@ -0,0 +1,98 @@
+// src/authoring/index.ts
+var secrets = (opts) => ({ kind: "secrets", ...opts });
+var oauth = (opts) => ({ kind: "oauth", ...opts });
+var RequirementKey = Symbol.for("executor/apps/requirement");
+var DynamicKey = Symbol.for("executor/apps/dynamic");
+var newRegistry = () => ({
+  app: void 0,
+  services: /* @__PURE__ */ new Map(),
+  tools: /* @__PURE__ */ new Map(),
+  dynamic: /* @__PURE__ */ new Map(),
+  problems: [],
+  toolFiles: /* @__PURE__ */ new Map()
+});
+var activeRegistry = newRegistry();
+var currentFile;
+var setActiveRegistry = (registry) => {
+  const previous = activeRegistry;
+  activeRegistry = registry;
+  return previous;
+};
+var __enterFile = (path) => {
+  currentFile = path;
+};
+var __leaveFile = () => {
+  currentFile = void 0;
+};
+var sourceFileFor = (claim) => {
+  if (currentFile !== void 0) return currentFile;
+  activeRegistry.problems.push({
+    message: `${claim} called outside an authored module import`
+  });
+  return "<unattributed>";
+};
+var makeTerminal = (spec) => ({
+  [RequirementKey]: spec,
+  describe: (text) => makeTerminal({ ...spec, description: text })
+});
+var service = (decl) => {
+  const file = sourceFileFor("service(...)");
+  const make = (spec) => ({
+    [RequirementKey]: spec,
+    decl,
+    optional: () => makeTerminal({ ...spec, arity: "optional" }),
+    array: () => makeTerminal({ ...spec, arity: "many" }),
+    grant: (name) => make({ ...spec, grant: name }),
+    describe: (text) => make({ ...spec, description: text })
+  });
+  const value = make({ service: decl, arity: "one" });
+  if (!activeRegistry.services.has(decl.origin))
+    activeRegistry.services.set(decl.origin, { decl, file });
+  return value;
+};
+var isRequirement = (value) => typeof value === "object" && value !== null && RequirementKey in value;
+var isService = (value) => isRequirement(value) && "decl" in value && "optional" in value && "array" in value && "grant" in value;
+var requirementSpecOf = (value) => isService(value) || isRequirement(value) ? value[RequirementKey] : void 0;
+var defineApp = (manifest) => {
+  const file = sourceFileFor("defineApp(...)");
+  const value = { kind: "executor-app", ...manifest };
+  if (activeRegistry.app === void 0) activeRegistry.app = value;
+  else activeRegistry.problems.push({ message: `${file}: duplicate defineApp(...)` });
+  return value;
+};
+var ToolKey = Symbol.for("executor/apps/tool");
+var defineTool = (spec) => {
+  const file = sourceFileFor("defineTool(...)");
+  const value = { [ToolKey]: spec };
+  const fileName = file.slice(file.lastIndexOf("/") + 1);
+  const stem = fileName.endsWith(".ts") ? fileName.slice(0, -3) : fileName;
+  const name = spec.name ?? stem;
+  const fileSummary = activeRegistry.toolFiles.get(file);
+  activeRegistry.toolFiles.set(file, {
+    definitions: (fileSummary?.definitions ?? 0) + 1,
+    hasUnnamedTool: fileSummary?.hasUnnamedTool === true || spec.name === void 0
+  });
+  const existing = activeRegistry.tools.get(name);
+  if (existing !== void 0) {
+    activeRegistry.problems.push({
+      message: `${file}: tool name '${name}' is already defined in ${existing.file}`
+    });
+  } else activeRegistry.tools.set(name, { spec, file });
+  return value;
+};
+var isTool = (value) => typeof value === "object" && value !== null && ToolKey in value;
+var toolSpecOf = (value) => isTool(value) ? value[ToolKey] : void 0;
+
+export {
+  secrets,
+  oauth,
+  newRegistry,
+  setActiveRegistry,
+  __enterFile,
+  __leaveFile,
+  service,
+  requirementSpecOf,
+  defineApp,
+  defineTool,
+  toolSpecOf
+};

package/dist/chunk-NFLNA2SC.js

@@ -0,0 +1,11 @@
+// src/runner/protocol.ts
+import { Data } from "effect";
+var CallError = class extends Data.TaggedError("CallError") {
+  get message() {
+    return `${this.target}: ${this.reason}`;
+  }
+};
+
+export {
+  CallError
+};

package/dist/chunk-RZA7AXBK.js

@@ -0,0 +1,107 @@
+// src/manifest/collect.ts
+var collectRegistry = (registry, compileInputSchema) => {
+  const requirementKey = Symbol.for("executor/apps/requirement");
+  const problems = registry.problems.map((problem) => problem.message);
+  const app = registry.app;
+  const requirementSpecOf = (value) => typeof value === "object" && value !== null && requirementKey in value ? value[requirementKey] : void 0;
+  const canonicalJson = (value) => {
+    const sortKeys = (node) => {
+      if (Array.isArray(node)) return node.map(sortKeys);
+      if (typeof node === "object" && node !== null)
+        return Object.fromEntries(
+          Object.entries(node).sort(([left], [right]) => left.localeCompare(right)).map(([key, child]) => [key, sortKeys(child)])
+        );
+      return node;
+    };
+    return JSON.stringify(sortKeys(value));
+  };
+  const claims = /* @__PURE__ */ new Map();
+  for (const [origin, registered] of registry.services) {
+    if (registered.file !== "app.ts") continue;
+    const { decl } = registered;
+    claims.set(origin, {
+      origin,
+      reach: decl.reach ?? [],
+      params: decl.params ?? {},
+      auth: decl.auth ?? {}
+    });
+  }
+  const collectRequirement = (role, requirement, where) => {
+    const spec = requirementSpecOf(requirement);
+    if (spec === void 0) {
+      problems.push(`${where}: requirement '${role}' is not a service/requirement value`);
+      return void 0;
+    }
+    const origin = spec.service.origin;
+    if (!claims.has(origin))
+      problems.push(`${where}: requirement '${role}' names ${origin}, which app.ts does not declare`);
+    if (spec.grant !== void 0 && !(spec.grant in (spec.service.auth ?? {})))
+      problems.push(
+        `${where}: requirement '${role}' pins grant '${spec.grant}', not a auth method on ${origin}`
+      );
+    return {
+      role,
+      service: origin,
+      arity: spec.arity,
+      ...spec.grant === void 0 ? {} : { grant: spec.grant },
+      ...spec.description === void 0 ? {} : { description: spec.description }
+    };
+  };
+  if (app === void 0) problems.push("app.ts must call defineApp({...})");
+  else if (typeof app.description !== "string" || app.description.trim().length === 0)
+    problems.push("app.ts: app description must not be empty");
+  for (const [file, summary] of registry.toolFiles) {
+    if (summary.definitions > 1 && summary.hasUnnamedTool)
+      problems.push(`${file}: multi-tool files must name every tool`);
+  }
+  const tools = [];
+  if (app !== void 0) {
+    for (const [name, registered] of registry.tools) {
+      const { spec, file } = registered;
+      const address = `${app.key}/${name}`;
+      if (typeof spec.description !== "string" || spec.description.trim().length === 0)
+        problems.push(`${file}: tool '${name}' description must not be empty`);
+      const requires = Object.entries(spec.requirements ?? {}).flatMap(([role, requirement]) => {
+        const collected = collectRequirement(role, requirement, address);
+        return collected === void 0 ? [] : [collected];
+      }).sort((left, right) => left.role.localeCompare(right.role));
+      let compiled;
+      try {
+        compiled = compileInputSchema(spec.input, address);
+      } catch (error) {
+        compiled = {
+          problem: `${address}: input schema could not compile to JSON schema (${error instanceof Error ? error.message : String(error)})`
+        };
+      }
+      if ("problem" in compiled) {
+        problems.push(compiled.problem);
+        continue;
+      }
+      tools.push({
+        address,
+        name,
+        description: spec.description,
+        inputSchema: compiled.value,
+        annotations: spec.annotations ?? {},
+        requires,
+        file
+      });
+    }
+  }
+  if (problems.length > 0 || app === void 0) return { problems };
+  const services = [...claims.values()].sort(
+    (left, right) => left.origin.localeCompare(right.origin)
+  );
+  const sortedTools = [...tools].sort((left, right) => left.address.localeCompare(right.address));
+  const appResult = { key: app.key, label: app.label, description: app.description };
+  const manifest = { app: appResult, services, tools: sortedTools };
+  return {
+    problems: [],
+    manifest,
+    canonical: canonicalJson(manifest)
+  };
+};
+
+export {
+  collectRegistry
+};

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The authoring surface: what app code imports. Pure and synchronous —
+ * no effect dependency, no node builtins — so authored files run
+ * unmodified in any execution environment, including sandboxed workers.
+ *
+ * Host-side machinery lives behind subpaths: "apps/manifest" loads and
+ * validates authored sources, "apps/runner" executes them.
+ */
+export * from "./authoring/index";

package/dist/index.js

@@ -0,0 +1,26 @@
+import {
+  __enterFile,
+  __leaveFile,
+  defineApp,
+  defineTool,
+  newRegistry,
+  oauth,
+  requirementSpecOf,
+  secrets,
+  service,
+  setActiveRegistry,
+  toolSpecOf
+} from "./chunk-LWKQDDLZ.js";
+export {
+  __enterFile,
+  __leaveFile,
+  defineApp,
+  defineTool,
+  newRegistry,
+  oauth,
+  requirementSpecOf,
+  secrets,
+  service,
+  setActiveRegistry,
+  toolSpecOf
+};

package/dist/manifest/collect.d.ts

@@ -0,0 +1,64 @@
+import type { AuthMethod, ParamSpec, Registry } from "../authoring/index";
+type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+type JsonSchemaObject = Readonly<Record<string, JsonValue>>;
+interface CollectedClaim {
+    readonly origin: string;
+    readonly reach: readonly string[];
+    readonly params: Readonly<Record<string, ParamSpec>>;
+    readonly auth: Readonly<Record<string, AuthMethod>>;
+}
+interface CollectedRequirement {
+    readonly role: string;
+    readonly service: string;
+    readonly arity: "one" | "optional" | "many";
+    readonly grant?: string;
+    readonly description?: string;
+}
+interface CollectedTool {
+    readonly address: string;
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: JsonSchemaObject;
+    readonly annotations: {
+        readonly readOnly?: boolean;
+        readonly destructive?: boolean;
+        readonly scopes?: readonly string[];
+    };
+    readonly requires: readonly CollectedRequirement[];
+    readonly file: string;
+}
+interface CollectedManifest {
+    readonly app: {
+        readonly key: string;
+        readonly label: string;
+        readonly description: string;
+    };
+    readonly services: readonly CollectedClaim[];
+    readonly tools: readonly CollectedTool[];
+}
+/** Result of compiling one authored input schema during registry projection. */
+export type InputSchemaCompilation = {
+    readonly value: JsonSchemaObject;
+} | {
+    readonly problem: string;
+};
+/** Registry projection before the deployment-specific digest implementation. */
+export type RegistryCollection = {
+    readonly problems: readonly string[];
+} | {
+    readonly problems: readonly [];
+    readonly manifest: CollectedManifest;
+    readonly canonical: string;
+};
+/**
+ * Validate and project an executed authoring registry into deterministic data.
+ *
+ * This function is deliberately closure-free: the workerd runner injects its
+ * source into the guest while the local manifest calls the same function
+ * directly. Schema compilation is supplied because each runtime owns its
+ * boundary decoder.
+ */
+export declare const collectRegistry: (registry: Registry, compileInputSchema: (input: object, where: string) => InputSchemaCompilation) => RegistryCollection;
+export {};

package/dist/manifest/contract.d.ts

@@ -0,0 +1,55 @@
+import { Schema } from "effect";
+import type { AuthMethod, ParamSpec } from "../authoring/index";
+/** A service claim projected from a registered declaration. */
+export interface CollectedClaim {
+    readonly origin: string;
+    readonly reach: readonly string[];
+    readonly params: Readonly<Record<string, ParamSpec>>;
+    readonly auth: Readonly<Record<string, AuthMethod>>;
+}
+/** A tool requirement projected from an authoring value. */
+export interface CollectedRequirement {
+    readonly role: string;
+    readonly service: string;
+    readonly arity: "one" | "optional" | "many";
+    readonly grant?: string;
+    readonly description?: string;
+}
+/** JSON object accepted for a persisted tool input schema. */
+export declare const JsonSchemaObject: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+export type JsonSchemaObject = typeof JsonSchemaObject.Type;
+/** A validated, publishable tool row. */
+export interface ManifestTool {
+    readonly address: string;
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: JsonSchemaObject;
+    readonly annotations: {
+        readonly readOnly?: boolean;
+        readonly destructive?: boolean;
+        readonly scopes?: readonly string[];
+    };
+    readonly requires: readonly CollectedRequirement[];
+    readonly file: string;
+}
+/** The deterministic public description of an executor app. */
+export interface AppManifestResult {
+    readonly digest: string;
+    readonly app: {
+        readonly key: string;
+        readonly label: string;
+        readonly description: string;
+    };
+    readonly services: readonly CollectedClaim[];
+    readonly tools: readonly ManifestTool[];
+}
+declare const PublishError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "PublishError";
+} & Readonly<A>;
+/** All publish-time authoring problems from one registry load. */
+export declare class PublishError extends PublishError_base<{
+    readonly problems: readonly string[];
+}> {
+    get message(): string;
+}
+export {};

package/dist/manifest/contract.js

@@ -0,0 +1,8 @@
+import {
+  JsonSchemaObject,
+  PublishError
+} from "../chunk-B7NEUIJL.js";
+export {
+  JsonSchemaObject,
+  PublishError
+};

package/dist/manifest/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 { Crypto, Effect, FileSystem } from "effect";
+import { type Registry } from "../authoring/index";
+import { PublishError, type AppManifestResult } from "./contract";
+export * from "./contract";
+/** 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 declare const loadApp: (appDir: string) => Effect.Effect<LoadedApp, PublishError, Crypto.Crypto | FileSystem.FileSystem>;
+/** Executes an app and returns its deterministic publish manifest. */
+export declare const manifest: (appDir: string) => Effect.Effect<AppManifestResult, PublishError, Crypto.Crypto | FileSystem.FileSystem>;

package/dist/manifest/index.js

@@ -0,0 +1,16 @@
+import {
+  loadApp,
+  manifest
+} from "../chunk-J5AVXTHA.js";
+import "../chunk-LWKQDDLZ.js";
+import {
+  JsonSchemaObject,
+  PublishError
+} from "../chunk-B7NEUIJL.js";
+import "../chunk-RZA7AXBK.js";
+export {
+  JsonSchemaObject,
+  PublishError,
+  loadApp,
+  manifest
+};

package/dist/runner/index.d.ts

@@ -0,0 +1,4 @@
+import { type AppRunner } from "./protocol";
+export * from "./protocol";
+/** Creates a permissive in-process runner for local development and tests. */
+export declare const localRunner: (appDir: string) => AppRunner;

package/dist/runner/index.js

@@ -0,0 +1,81 @@
+import {
+  loadApp
+} from "../chunk-J5AVXTHA.js";
+import "../chunk-LWKQDDLZ.js";
+import "../chunk-B7NEUIJL.js";
+import {
+  CallError
+} from "../chunk-NFLNA2SC.js";
+import "../chunk-RZA7AXBK.js";
+
+// src/runner/index.ts
+import { Effect } from "effect";
+var hasStandardValidate = (input) => "~standard" in input && typeof input["~standard"].validate === "function";
+var parseInput = (name, spec, input) => {
+  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 === void 0 ? Effect.succeed(result.value) : Effect.fail(
+        new CallError({
+          target: name,
+          reason: `invalid input (${result.issues.map((issue) => issue.message).join("; ")})`
+        })
+      )
+    )
+  );
+};
+var localRunner = (appDir) => {
+  let cachedLoad;
+  const loaded = () => Effect.suspend(() => {
+    if (cachedLoad !== void 0) return cachedLoad;
+    return Effect.flatMap(
+      Effect.cached(loadApp(appDir)),
+      (effect) => Effect.sync(() => {
+        cachedLoad = effect;
+        return effect;
+      }).pipe(Effect.flatten)
+    );
+  });
+  const loadedFor = (target) => 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 === void 0)
+        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(
+          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" }))
+  };
+};
+export {
+  CallError,
+  localRunner
+};

package/dist/runner/protocol.d.ts

@@ -0,0 +1,28 @@
+import { Crypto, 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>>;
+declare const CallError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CallError";
+} & Readonly<A>;
+/** A runner operation failure associated with its target. */
+export declare class CallError extends CallError_base<{
+    readonly target: string;
+    readonly reason: string;
+}> {
+    get message(): string;
+}
+/** 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>;
+}
+export {};

package/dist/runner/protocol.js

@@ -0,0 +1,6 @@
+import {
+  CallError
+} from "../chunk-NFLNA2SC.js";
+export {
+  CallError
+};

package/dist/workerd/index.d.ts

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

package/dist/workerd/index.js

@@ -0,0 +1,6 @@
+import {
+  collectRegistry
+} from "../chunk-RZA7AXBK.js";
+export {
+  collectRegistry
+};

package/package.json

@@ -1,47 +1,61 @@
 {
   "name": "apps",
-  "version": "0.8.3",
-  "description": "Create, validate, and render Heroku app.json manifests",
-  "main": "index.js",
-  "bin": {
-    "app": "./bin/apps",
-    "apps": "./bin/apps"
-  },
-  "scripts": {
-    "test": "mocha",
-    "build": "bin/build",
-    "doc": "bin/doc"
-  },
+  "version": "1.0.0-beta.1",
+  "description": "Author executor apps: declare services, auth, and tools in plain TypeScript; the executor platform runs, validates, and serves them.",
+  "license": "MIT",
+  "type": "module",
   "repository": {
     "type": "git",
-    "url": "https://github.com/heroku/apps"
+    "url": "git+https://github.com/UsefulSoftwareCo/executor-rework.git",
+    "directory": "sdk/apps"
   },
-  "keywords": [
-    "app.json"
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "README.md"
   ],
-  "author": "Zeke Sikelianos <zeke@sikelianos.com> (http://zeke.sikelianos.com/)",
-  "license": "ISC",
-  "bugs": {
-    "url": "https://github.com/heroku/apps/issues"
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./authoring": {
+      "types": "./dist/authoring/index.d.ts",
+      "default": "./dist/authoring/index.js"
+    },
+    "./manifest": {
+      "types": "./dist/manifest/index.d.ts",
+      "default": "./dist/manifest/index.js"
+    },
+    "./manifest/contract": {
+      "types": "./dist/manifest/contract.d.ts",
+      "default": "./dist/manifest/contract.js"
+    },
+    "./runner": {
+      "types": "./dist/runner/index.d.ts",
+      "default": "./dist/runner/index.js"
+    },
+    "./runner/protocol": {
+      "types": "./dist/runner/protocol.d.ts",
+      "default": "./dist/runner/protocol.js"
+    },
+    "./workerd": {
+      "types": "./dist/workerd/index.d.ts",
+      "default": "./dist/workerd/index.js"
+    }
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-beta.93"
   },
-  "homepage": "https://github.com/heroku/apps",
-  "dependencies": {
-    "revalidator": "https://github.com/facundoolano/revalidator/tarball/master",
-    "github-url-to-object": "^0.4.1",
-    "superagent": "^0.17.0",
-    "browserify-hogan": "^0.1.2",
-    "hogan.js": "^2.0.0",
-    "brfs": "^1.0.2",
-    "async": "^0.7.0",
-    "heroku-client": "^1.2.0",
-    "commander": "^2.2.0",
-    "marked": "^0.3.2"
+  "peerDependenciesMeta": {
+    "effect": {
+      "optional": false
+    }
   },
   "devDependencies": {
-    "mocha": "^1.18.0",
-    "browserify": "^3.38.0",
-    "uglify-js": "^2.4.13",
-    "cheerio": "^0.15.0",
-    "nixt": "^0.3.0"
+    "@types/node": "22",
+    "esbuild": "0.25",
+    "typescript": "5.9.3"
   }
-}
+}