apps 0.8.3 → 1.0.0-beta.1

package/README.md

@@ -1,168 +1,53 @@
 # apps
 
-[apps](https://www.npmjs.org/package/apps) is a node module for creating and validating Heroku app.json files. It works in node.js and the browser, and also has a CLI.
-
-## Schema
-
-The app.json schema is defined using the [JSON Schema](http://json-schema.org/)
-specification and is validated with the awesome
-[revalidator](https://github.com/flatiron/revalidator#readme) node module.
-
-See the schema at [schema.js](/schema.js).
-
-## Installation and Usage
-
-### Programmatic usage with Node.js or Browserify
-
-Download the module from npm and save it to your package.json:
-
-```sh
-npm install apps --save
-```
-
-Require it in your script:
-
-```js
-var App = require("apps")
-```
-
-### Usage in the Browser (without Browserify)
-
-If browserify isn't your thing, use the pre-compiled browser-ready bundle in
-[dist/app.js](/dist/app.js). Include this file in your html page and it will create
-`window.App` for you.
-
-### Usage on the Command Line
-
-To use this module on the command line, you'll need to install it globally using npm:
-
-```sh
-npm install apps --global
-```
-
-Now you can run `app` or `apps` from any directory:
-
-```sh
-$ app
-
-  Usage: app [options] [command]
-
-  Commands:
-
-    schema [options]       Write the app.json schema to STDOUT
-
-  Options:
-
-    -h, --help     output usage information
-    -V, --version  output the version number
-
-  Use 'app <command> --help' to get more information about a specific command.
-```
-
-## Class Methods
-
-### App.new(payload)
-
-Instantiate with a JSON filename:
-
-```js
-var app = App.new(__dirname + "/path/to/app.json")
-```
-
-Instantiate with a JSON string:
-
-```js
-var json = "{name: \"small-sharp-tool\", description: \"This app does one little thing, and does it well.\"}"
-var app = App.new(json)
-```
-
-Instantiate with a JavaScript object:
-
-```js
-var app = App.new({
-  name: "small-sharp-tool",
-  description: "This app does one little thing, and does it well."
-})
-```
-
-### App.fetch(url, callback)
-
-You can fetch app manifests straight from GitHub. The
-[github-raw-cors-proxy](https://github.com/zeke/github-raw-cors-proxy) service is used
-to make the `app.json` file downloadable from browsers.
-
-`url` can be a fully qualified GitHub URL, or a shorthand `user/repo` string:
-
-```js
-App.fetch('zeke/harp-slideshow-template', function(err, manifest) {
-  console.log(err, manifest)
-})
-```
-
-### App.example
-
-Generates an example manifest from example content in the [schema](/schema.js).
-
-```js
-App.example
-```
-
-## Instance Methods
-
-### app.valid
-
-A getter method that validates the app manifest and returns `true` or `false`
-
-### app.errors
-
-Returns `null` if app manifest is valid.
-
-Returns an array of error objects if invalid:
-
-```js
-[
-  {property: "name", message: "is required"},
-  {property: "website", message: "is not a valid url"}
-]
-```
-
-### app.toJSON()
-
-Return a pretty JSON string representation of the manifest, without any superfluous properties.
-
-### app.getAddonPrices(callback)
-
-Fetch pricing data about the app's required addons by hitting the Heroku Platform API.
-
-## Tests
-
-```
-npm install
-npm test
-```
-
-## Bundle
-
-To prepare a browser-ready bundle, run the following:
-
-```sh
-npm run build
-
-# Wrote dist/app.js
-# Wrote dist/app.min.js
-```
-
-## Docs
-
-Genarate human-friendly docs from the schema
-
-```sh
-npm run docs
-
-# Wrote dist/schema.md
-# Wrote dist/schema.html
-```
-
-## License
-
-MIT
+Author executor apps in plain TypeScript: declare the services a tool talks
+to, the auth they need, and the tools themselves. The executor platform loads,
+validates, and serves them; credentials never enter your handler — each
+requirement arrives as a capability that spends them for you.
+
+> `1.0.0-beta.x` is a new package under this name, unrelated to `0.x`.
+
+```ts
+// app.ts
+import { defineApp, secrets, service } from "apps";
+
+export const github = service({
+  origin: "api.github.com",
+  label: "GitHub",
+  auth: {
+    pat: secrets({
+      label: "Personal access token",
+      help: "Create a fine-grained token at github.com/settings/tokens.",
+      fields: { token: { label: "Token", secret: true } },
+    }),
+  },
+});
+
+export default defineApp({
+  key: "github",
+  label: "GitHub",
+  description: "Repositories, issues, and pull requests.",
+});
+```
+
+```ts
+// tools/get-repo.ts
+import { defineTool } from "apps";
+import { z } from "zod";
+import { github } from "../app";
+
+export default defineTool({
+  description: "Fetch a repository",
+  input: z.object({ owner: z.string(), repo: z.string() }),
+  requirements: { gh: github },
+  handler: async ({ owner, repo }, ctx) => {
+    const response = await ctx.gh.fetch(`/repos/${owner}/${repo}`);
+    return response.json();
+  },
+});
+```
+
+The root export is pure and synchronous — no effect dependency, no node
+builtins — so authored files run unmodified anywhere, including sandboxed
+workers. Host machinery lives behind subpaths (`apps/manifest`,
+`apps/runner`) and requires `effect`.

package/dist/authoring/index.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Synchronous authoring primitives imported by app.ts and tools/*.ts.
+ * Authored modules record plain claims without I/O or user context; the
+ * manifest loader owns execution, validation, and effects.
+ */
+export interface SecretsMethod<F extends Readonly<Record<string, SecretField>> = Readonly<Record<string, SecretField>>> {
+    readonly kind: "secrets";
+    readonly label: string;
+    /** Markdown shown under this auth method on the connect page, for example:
+     * "Create a fine-grained token at github.com/settings/tokens." */
+    readonly help?: string;
+    readonly fields: F;
+}
+export interface SecretField {
+    readonly label: string;
+    /** Form masking. Stated, never guessed from the field name. */
+    readonly secret: boolean;
+}
+/**
+ * An oauth auth method is a secrets-shaped auth method with acquisition strategies
+ * layered on: the material contract is always {token, refresh_token?,
+ * expires_at?}, and the host fills it by the best strategy it can offer
+ * — authorization-code ceremony, device-code ceremony, or paste. Paste
+ * is the always-on floor (a pasted token spends identically), so the
+ * auth method works on any deployment; ceremony is progressive enhancement.
+ * Handlers cannot tell how material arrived.
+ */
+export interface OAuthMethod {
+    readonly kind: "oauth";
+    readonly label: string;
+    /** Markdown shown under this auth method on the connect page, for example:
+     * "Create a fine-grained token at github.com/settings/tokens." */
+    readonly help?: string;
+    /** Endpoints only when the service publishes no well-knowns —
+     * discovery (RFC 9728 + AS metadata) outranks these when present.
+     * Authors state facts about the service, never about the client. */
+    readonly authorizationEndpoint?: string;
+    readonly tokenEndpoint?: string;
+    readonly scopes?: readonly string[];
+    /** Set false only when a user-pasted token genuinely cannot work
+     * (audience-bound tokens, DPoP). Stated, never inferred. */
+    readonly paste?: false;
+}
+export type AuthMethod = SecretsMethod | OAuthMethod;
+export declare const secrets: <const F extends Readonly<Record<string, SecretField>>>(opts: {
+    readonly label: string;
+    /** Markdown shown under this auth method on the connect page, for example:
+     * "Create a fine-grained token at github.com/settings/tokens." */
+    readonly help?: string;
+    readonly fields: F;
+}) => SecretsMethod<F>;
+export declare const oauth: (opts: {
+    readonly label: string;
+    /** Markdown shown under this auth method on the connect page, for example:
+     * "Create a fine-grained token at github.com/settings/tokens." */
+    readonly help?: string;
+    readonly authorizationEndpoint?: string;
+    readonly tokenEndpoint?: string;
+    readonly scopes?: readonly string[];
+    readonly paste?: false;
+}) => OAuthMethod;
+export interface ServiceDecl {
+    /** Canonical origin, possibly templated: "https://{region}.posthog.com". */
+    readonly origin: string;
+    /** Hosts beyond the origin the credential legitimately travels to. */
+    readonly reach?: readonly string[];
+    /** Connection-scoped non-secret connect-form values; keys may fill
+     * origin templates. */
+    readonly params?: Readonly<Record<string, ParamSpec>>;
+    /** Named auth methods. Key = the grant name tools switch on. */
+    readonly auth?: Readonly<Record<string, AuthMethod>>;
+}
+export interface ParamSpec {
+    readonly label: string;
+    readonly options?: readonly string[];
+}
+/** What the manifest pipeline reads off a requirement value. */
+export interface RequirementSpec {
+    readonly service: ServiceDecl;
+    readonly arity: "one" | "optional" | "many";
+    readonly grant?: string;
+    readonly description?: string;
+}
+declare const RequirementKey: unique symbol;
+/**
+ * A requirement value in a tool's `requirements` record. A Service IS
+ * a requirement (bare value = arity "one"); .optional()/.array()
+ * return terminal Requirements so nonsense chains do not typecheck.
+ */
+export interface Requirement<D extends ServiceDecl = ServiceDecl> {
+    readonly [RequirementKey]: RequirementSpec;
+    describe(text: string): Requirement<D>;
+}
+export interface Service<D extends ServiceDecl = ServiceDecl> extends Requirement<D> {
+    readonly decl: D;
+    optional(): Requirement<D>;
+    array(): Requirement<D>;
+    /** Pin one auth method: this tool supports only the named grant. */
+    grant(name: keyof NonNullable<D["auth"]> & string): Service<D>;
+    describe(text: string): Service<D>;
+}
+/** A publish-time authoring problem accumulated without interrupting defines. */
+export interface Problem {
+    readonly message: string;
+}
+/**
+ * A dynamic tool-set claim: tools discovered from a live surface (an
+ * MCP server's tool list, an OpenAPI document) rather than authored one
+ * file at a time. The claim is recorded at publish time; discovery runs
+ * later, per connection — an app with zero static tools and one claim
+ * saves green, and listing never blocks on an upstream.
+ */
+export type DynamicClaimSpec = {
+    readonly kind: "mcp";
+    readonly requirement: RequirementSpec;
+    /** MCP endpoint URL. Absent = the service origin at its root path. */
+    readonly endpoint?: string;
+} | {
+    readonly kind: "openapi";
+    readonly requirement: RequirementSpec;
+    /** OpenAPI document: an absolute URL or an app-relative path. */
+    readonly spec: string;
+};
+declare const DynamicKey: unique symbol;
+/** The value fromMCP/fromOpenAPI return: an opaque claim handle a tool
+ * file default-exports. The spec is undefined when the claim was
+ * invalid (a problem was recorded instead). */
+export interface DynamicToolSet {
+    readonly [DynamicKey]: DynamicClaimSpec | undefined;
+}
+/** A registered dynamic claim and its source attribution. @internal */
+export interface RegisteredDynamic {
+    readonly spec: DynamicClaimSpec;
+    readonly file: string;
+}
+/** A registered service declaration and its source attribution. @internal */
+export interface RegisteredService {
+    readonly decl: ServiceDecl;
+    readonly file: string;
+}
+/** A registered tool declaration and its source attribution. @internal */
+export interface RegisteredTool {
+    readonly spec: ToolSpec;
+    readonly file: string;
+}
+/** Mutable claim registry populated while authored modules execute. @internal */
+export interface Registry {
+    app: AppManifest | undefined;
+    readonly services: Map<string, RegisteredService>;
+    readonly tools: Map<string, RegisteredTool>;
+    readonly dynamic: Map<string, RegisteredDynamic>;
+    readonly problems: Problem[];
+    readonly toolFiles: Map<string, {
+        definitions: number;
+        hasUnnamedTool: boolean;
+    }>;
+}
+/** Creates an isolated empty authoring registry. @internal */
+export declare const newRegistry: () => Registry;
+/** Swaps the registry receiving subsequent authoring claims. @internal */
+export declare const setActiveRegistry: (registry: Registry) => Registry;
+/** Sets source-file attribution for subsequent authoring claims. @internal */
+export declare const __enterFile: (path: string) => void;
+/** Clears source-file attribution after an authored module import. @internal */
+export declare const __leaveFile: () => void;
+export declare const service: <const D extends ServiceDecl>(decl: D) => Service<D>;
+export declare const requirementSpecOf: (value: unknown) => RequirementSpec | undefined;
+export interface AppManifest {
+    readonly kind: "executor-app";
+    readonly key: string;
+    readonly label: string;
+    readonly description: string;
+}
+export declare const defineApp: (manifest: {
+    readonly key: string;
+    readonly label: string;
+    readonly description: string;
+}) => AppManifest;
+/** Any Standard Schema (zod preferred) or a raw JSON-schema object. */
+export type SchemaLike = object;
+export interface ToolAnnotations {
+    readonly readOnly?: boolean;
+    readonly destructive?: boolean;
+    /** Facts, not flow: shortfall surfaces as the scope challenge. */
+    readonly scopes?: readonly string[];
+}
+export interface ToolSpec {
+    /** Address segment. Single-tool files may omit it (filename). */
+    readonly name?: string;
+    readonly description: string;
+    readonly requirements?: Readonly<Record<string, Requirement>>;
+    readonly input: SchemaLike;
+    readonly output?: SchemaLike;
+    readonly annotations?: ToolAnnotations;
+    handler(input: never, ctx: never): Promise<unknown>;
+}
+declare const ToolKey: unique symbol;
+export interface Tool {
+    readonly [ToolKey]: ToolSpec;
+}
+export declare const defineTool: (spec: ToolSpec) => Tool;
+export declare const toolSpecOf: (value: unknown) => ToolSpec | undefined;
+/** A tool file's default export. */
+export type ToolExport = Tool | ReadonlyArray<Tool>;
+export {};

package/dist/authoring/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/chunk-B7NEUIJL.js

@@ -0,0 +1,14 @@
+// src/manifest/contract.ts
+import { Data, Schema } from "effect";
+var JsonSchemaObject = Schema.Record(Schema.String, Schema.Json);
+var PublishError = class extends Data.TaggedError("PublishError") {
+  get message() {
+    return `publish failed:
+${this.problems.map((problem) => `  - ${problem}`).join("\n")}`;
+  }
+};
+
+export {
+  JsonSchemaObject,
+  PublishError
+};

package/dist/chunk-J5AVXTHA.js

@@ -0,0 +1,154 @@
+import {
+  __enterFile,
+  __leaveFile,
+  newRegistry,
+  setActiveRegistry
+} from "./chunk-LWKQDDLZ.js";
+import {
+  JsonSchemaObject,
+  PublishError
+} from "./chunk-B7NEUIJL.js";
+import {
+  collectRegistry
+} from "./chunk-RZA7AXBK.js";
+
+// src/manifest/index.ts
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { Crypto, Effect, FileSystem, Schema, Semaphore } from "effect";
+var hasStandardJsonSchema = (input) => "~standard" in input && typeof input["~standard"].jsonSchema?.input === "function";
+var compileInputSchema = (input, where) => {
+  if ("~standard" in input) {
+    if (!hasStandardJsonSchema(input))
+      return {
+        problem: `${where}: input is a Standard Schema without the jsonSchema extension \u2014 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) };
+  } catch (error) {
+    return { problem: schemaPublishProblem(where, error) };
+  }
+};
+var schemaPublishProblem = (where, error) => `${where}: input schema could not compile to JSON schema (${error instanceof Error ? error.message : String(error)})`;
+var strictify = (node) => {
+  if (typeof node !== "object" || node === null) return node;
+  if (Array.isArray(node)) return node.map(strictify);
+  const object = { ...node };
+  if (object.type === "object" && object.additionalProperties === void 0)
+    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] !== void 0 && typeof object[key] === "object" && object[key] !== null)
+      object[key] = Object.fromEntries(
+        Object.entries(object[key]).map(([name, value]) => [
+          name,
+          strictify(value)
+        ])
+      );
+  return object;
+};
+var digestOf = (content) => 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("");
+});
+var loadPermit = Semaphore.makeUnsafe(1);
+var runNonce = 0;
+var baseAppImports = /* @__PURE__ */ new Set();
+var moduleFailure = (where, error) => new PublishError({
+  problems: [
+    `${where}: failed to execute (${error instanceof Error ? error.message : String(error)})`
+  ]
+});
+var canonicalModuleUrl = (path, where) => Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  const realPath = yield* fs.realPath(path).pipe(
+    Effect.mapError((error) => moduleFailure(where, error))
+  );
+  return pathToFileURL(realPath);
+});
+var importModule = (specifier, where) => Effect.tryPromise({
+  try: () => import(specifier).then(() => void 0),
+  catch: (error) => moduleFailure(where, error)
+});
+var recordModuleProblems = (registry, effect) => effect.pipe(
+  Effect.catchTag(
+    "PublishError",
+    (error) => Effect.sync(() => {
+      registry.problems.push(...error.problems.map((message) => ({ message })));
+    })
+  )
+);
+var executeModules = (appDir, files) => 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;
+    })
+  )
+);
+var loadApp = (appDir) => 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
+    }
+  };
+});
+var manifest = (appDir) => Effect.map(loadApp(appDir), ({ result }) => result);
+
+export {
+  loadApp,
+  manifest
+};